@sentry/replay 7.59.0-beta.0 → 7.59.1

package/esm/index.js

@@ -14,6 +14,9 @@ const UNABLE_TO_SEND_REPLAY = 'Unable to send Replay';
 // The idle limit for a session after which recording is paused.
 const SESSION_IDLE_PAUSE_DURATION = 300000; // 5 minutes in ms
 
+// The idle limit for a session after which the session expires.
+const SESSION_IDLE_EXPIRE_DURATION = 900000; // 15 minutes in ms
+
 // The maximum length of a session
 const MAX_SESSION_LIFE = 3600000; // 60 minutes in ms
 
@@ -3276,26 +3279,26 @@ function addBreadcrumbEvent(replay, breadcrumb) {
   }
 
   if (['ui.click', 'ui.input'].includes(breadcrumb.category )) {
-    replay.updateUserActivity();
+    replay.triggerUserActivity();
+  } else {
+    replay.checkAndHandleExpiredSession();
   }
 
-  replay.checkSessionState(() => {
-    replay.addUpdate(() => {
-      void replay.throttledAddEvent({
-        type: EventType.Custom,
-        // TODO: We were converting from ms to seconds for breadcrumbs, spans,
-        // but maybe we should just keep them as milliseconds
-        timestamp: (breadcrumb.timestamp || 0) * 1000,
-        data: {
-          tag: 'breadcrumb',
-          // normalize to max. 10 depth and 1_000 properties per object
-          payload: normalize(breadcrumb, 10, 1000),
-        },
-      });
-
-      // Do not flush after console log messages
-      return breadcrumb.category === 'console';
+  replay.addUpdate(() => {
+    void replay.throttledAddEvent({
+      type: EventType.Custom,
+      // TODO: We were converting from ms to seconds for breadcrumbs, spans,
+      // but maybe we should just keep them as milliseconds
+      timestamp: (breadcrumb.timestamp || 0) * 1000,
+      data: {
+        tag: 'breadcrumb',
+        // normalize to max. 10 depth and 1_000 properties per object
+        payload: normalize(breadcrumb, 10, 1000),
+      },
     });
+
+    // Do not flush after console log messages
+    return breadcrumb.category === 'console';
   });
 }
 
@@ -4386,69 +4389,14 @@ function createEventBuffer({ useCompression }) {
   return new EventBufferArray();
 }
 
-/**
- * Given an initial timestamp and an expiry duration, checks to see if current
- * time should be considered as expired.
- */
-function isExpired(
-  initialTime,
-  expiry,
-  targetTime = +new Date(),
-) {
-  // Always expired if < 0
-  if (initialTime === null || expiry === undefined || expiry < 0) {
-    return true;
-  }
-
-  // Never expires if == 0
-  if (expiry === 0) {
-    return false;
-  }
-
-  return initialTime + expiry <= targetTime;
-}
-
-/** Check the state of the session. */
-function checkSessionState(
-  session,
-  recordingMode,
-  timeouts,
-  callbacks
-
-,
-) {
-  const _isIdle = () => {
-    return isExpired(session.lastActivity, timeouts.sessionIdlePause);
-  };
-
-  const _exceedsMaxLength = () => {
-    return isExpired(session.started, timeouts.maxSessionLife);
-  };
-
-  // When buffering, we never want to expire/end/pause/restart the recording
-  if (recordingMode === 'buffer') {
-    callbacks.onContinue();
-    return;
-  }
-
-  if (_exceedsMaxLength()) {
-    callbacks.onEnd();
-    return;
-  }
-
-  if (_isIdle()) {
-    callbacks.onPause();
-    return;
-  }
-
-  callbacks.ensureResumed();
-
-  callbacks.onContinue();
-}
-
 /** If sessionStorage is available. */
 function hasSessionStorage() {
-  return 'sessionStorage' in WINDOW && !!WINDOW.sessionStorage;
+  try {
+    // This can throw, e.g. when being accessed in a sandboxed iframe
+    return 'sessionStorage' in WINDOW && !!WINDOW.sessionStorage;
+  } catch (e) {
+    return false;
+  }
 }
 
 /**
@@ -4474,6 +4422,41 @@ function deleteSession() {
   }
 }
 
+/**
+ * Given an initial timestamp and an expiry duration, checks to see if current
+ * time should be considered as expired.
+ */
+function isExpired(
+  initialTime,
+  expiry,
+  targetTime = +new Date(),
+) {
+  // Always expired if < 0
+  if (initialTime === null || expiry === undefined || expiry < 0) {
+    return true;
+  }
+
+  // Never expires if == 0
+  if (expiry === 0) {
+    return false;
+  }
+
+  return initialTime + expiry <= targetTime;
+}
+
+/**
+ * Checks to see if session is expired
+ */
+function isSessionExpired(session, timeouts, targetTime = +new Date()) {
+  return (
+    // First, check that maximum session length has not been exceeded
+    isExpired(session.started, timeouts.maxSessionLife, targetTime) ||
+    // check that the idle timeout has not been exceeded (i.e. user has
+    // performed an action within the last `sessionIdleExpire` ms)
+    isExpired(session.lastActivity, timeouts.sessionIdleExpire, targetTime)
+  );
+}
+
 /**
  * Given a sample rate, returns true if replay should be sampled.
  *
@@ -4522,20 +4505,24 @@ function makeSession(session) {
     lastActivity,
     segmentId,
     sampled,
+    shouldRefresh: true,
   };
 }
 
+/**
+ * Get the sampled status for a session based on sample rates & current sampled status.
+ */
+function getSessionSampleType(sessionSampleRate, allowBuffering) {
+  return isSampled(sessionSampleRate) ? 'session' : allowBuffering ? 'buffer' : false;
+}
+
 /**
  * Create a new session, which in its current implementation is a Sentry event
  * that all replays will be saved to as attachments. Currently, we only expect
  * one of these Sentry events per "replay session".
  */
-function createSession({
-  sampled,
-  stickySession = false,
-}
-
-) {
+function createSession({ sessionSampleRate, allowBuffering, stickySession = false }) {
+  const sampled = getSessionSampleType(sessionSampleRate, allowBuffering);
   const session = makeSession({
     sampled,
   });
@@ -4573,31 +4560,47 @@ function fetchSession() {
   }
 }
 
-/** Either restore a session from sessionStorage, or create a new one. */
-function restoreOrCreateSession({
+/**
+ * Get or create a session
+ */
+function getSession({
+  timeouts,
+  currentSession,
   stickySession,
-  sampled,
-  forceSampled,
-}
-
-) {
-  const currentSession = stickySession && fetchSession();
-
-  if (currentSession && currentSession.sampled !== sampled && forceSampled) {
-    // If for whatever reason the session from sessionStorage has a different sampling, we force to the new sampling
-    (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) &&
-      logger.log(`[Replay] Tried to restore session with different sampling: ${currentSession.sampled} !== ${sampled}`);
-  } else if (currentSession) {
-    (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log(`[Replay] Loaded session from sessionStorage: id=${currentSession.id}`);
-    return currentSession;
+  sessionSampleRate,
+  allowBuffering,
+}) {
+  // If session exists and is passed, use it instead of always hitting session storage
+  const session = currentSession || (stickySession && fetchSession());
+
+  if (session) {
+    // If there is a session, check if it is valid (e.g. "last activity" time
+    // should be within the "session idle time", and "session started" time is
+    // within "max session time").
+    const isExpired = isSessionExpired(session, timeouts);
+
+    if (!isExpired || (allowBuffering && session.shouldRefresh)) {
+      return { type: 'saved', session };
+    } else if (!session.shouldRefresh) {
+      // This is the case if we have an error session that is completed
+      // (=triggered an error). Session will continue as session-based replay,
+      // and when this session is expired, it will not be renewed until user
+      // reloads.
+      const discardedSession = makeSession({ sampled: false });
+      return { type: 'new', session: discardedSession };
+    } else {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log('[Replay] Session has expired');
+    }
+    // Otherwise continue to create a new session
   }
 
   const newSession = createSession({
     stickySession,
-    sampled,
+    sessionSampleRate,
+    allowBuffering,
   });
 
-  return newSession;
+  return { type: 'new', session: newSession };
 }
 
 function isCustomEvent(event) {
@@ -4640,10 +4643,7 @@ async function addEvent(
 
     const replayOptions = replay.getOptions();
 
-    const eventAfterPossibleCallback =
-      typeof replayOptions.beforeAddRecordingEvent === 'function' && isCustomEvent(event)
-        ? replayOptions.beforeAddRecordingEvent(event)
-        : event;
+    const eventAfterPossibleCallback = maybeApplyCallback(event, replayOptions.beforeAddRecordingEvent);
 
     if (!eventAfterPossibleCallback) {
       return;
@@ -4664,6 +4664,23 @@ async function addEvent(
   }
 }
 
+function maybeApplyCallback(
+  event,
+  callback,
+) {
+  try {
+    if (typeof callback === 'function' && isCustomEvent(event)) {
+      return callback(event);
+    }
+  } catch (error) {
+    (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) &&
+      logger.error('[Replay] An error occured in the `beforeAddRecordingEvent` callback, skipping the event...', error);
+    return null;
+  }
+
+  return event;
+}
+
 /** If the event is an error event */
 function isErrorEvent(event) {
   return !event.type;
@@ -4910,14 +4927,12 @@ function handleHistorySpanListener(replay) {
 
     // Need to collect visited URLs
     replay.getContext().urls.push(result.name);
-    replay.updateUserActivity();
+    replay.triggerUserActivity();
 
-    replay.checkSessionState(() => {
-      replay.addUpdate(() => {
-        createPerformanceSpans(replay, [result]);
-        // Returning false to flush
-        return false;
-      });
+    replay.addUpdate(() => {
+      createPerformanceSpans(replay, [result]);
+      // Returning false to flush
+      return false;
     });
   };
 }
@@ -6533,64 +6548,79 @@ function getHandleRecordingEmit(replay) {
   let hadFirstEvent = false;
 
   return (event, _isCheckout) => {
-    replay.checkSessionState(() => {
-      // `_isCheckout` is only set when the checkout is due to `checkoutEveryNms`
-      // We also want to treat the first event as a checkout, so we handle this specifically here
-      const isCheckout = _isCheckout || !hadFirstEvent;
-      hadFirstEvent = true;
-
-      // The handler returns `true` if we do not want to trigger debounced flush, `false` if we want to debounce flush.
-      replay.addUpdate(() => {
-        // The session is always started immediately on pageload/init, but for
-        // error-only replays, it should reflect the most recent checkout
-        // when an error occurs. Clear any state that happens before this current
-        // checkout. This needs to happen before `addEvent()` which updates state
-        // dependent on this reset.
-        if (replay.recordingMode === 'buffer' && isCheckout) {
-          replay.setInitialState();
-        }
+    // If this is false, it means session is expired, create and a new session and wait for checkout
+    if (!replay.checkAndHandleExpiredSession()) {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.warn('[Replay] Received replay event after session expired.');
 
-        // We need to clear existing events on a checkout, otherwise they are
-        // incremental event updates and should be appended
-        void addEvent(replay, event, isCheckout);
+      return;
+    }
 
-        // Different behavior for full snapshots (type=2), ignore other event types
-        // See https://github.com/rrweb-io/rrweb/blob/d8f9290ca496712aa1e7d472549480c4e7876594/packages/rrweb/src/types.ts#L16
-        if (!isCheckout) {
-          return false;
-        }
+    // `_isCheckout` is only set when the checkout is due to `checkoutEveryNms`
+    // We also want to treat the first event as a checkout, so we handle this specifically here
+    const isCheckout = _isCheckout || !hadFirstEvent;
+    hadFirstEvent = true;
 
-        // Additionally, create a meta event that will capture certain SDK settings.
-        // In order to handle buffer mode, this needs to either be done when we
-        // receive checkout events or at flush time.
-        //
-        // `isCheckout` is always true, but want to be explicit that it should
-        // only be added for checkouts
-        void addSettingsEvent(replay, isCheckout);
-
-        // When in buffer mode, make sure we adjust the session started date to the current earliest event of the buffer
-        // this should usually be the timestamp of the checkout event, but to be safe...
-        if (replay.recordingMode === 'buffer' && replay.session && replay.eventBuffer) {
-          const earliestEvent = replay.eventBuffer.getEarliestTimestamp();
-          if (earliestEvent) {
-            replay.session.started = earliestEvent;
-
-            if (replay.getOptions().stickySession) {
-              saveSession(replay.session);
-            }
+    // The handler returns `true` if we do not want to trigger debounced flush, `false` if we want to debounce flush.
+    replay.addUpdate(() => {
+      // The session is always started immediately on pageload/init, but for
+      // error-only replays, it should reflect the most recent checkout
+      // when an error occurs. Clear any state that happens before this current
+      // checkout. This needs to happen before `addEvent()` which updates state
+      // dependent on this reset.
+      if (replay.recordingMode === 'buffer' && isCheckout) {
+        replay.setInitialState();
+      }
+
+      // We need to clear existing events on a checkout, otherwise they are
+      // incremental event updates and should be appended
+      void addEvent(replay, event, isCheckout);
+
+      // Different behavior for full snapshots (type=2), ignore other event types
+      // See https://github.com/rrweb-io/rrweb/blob/d8f9290ca496712aa1e7d472549480c4e7876594/packages/rrweb/src/types.ts#L16
+      if (!isCheckout) {
+        return false;
+      }
+
+      // Additionally, create a meta event that will capture certain SDK settings.
+      // In order to handle buffer mode, this needs to either be done when we
+      // receive checkout events or at flush time.
+      //
+      // `isCheckout` is always true, but want to be explicit that it should
+      // only be added for checkouts
+      void addSettingsEvent(replay, isCheckout);
+
+      // If there is a previousSessionId after a full snapshot occurs, then
+      // the replay session was started due to session expiration. The new session
+      // is started before triggering a new checkout and contains the id
+      // of the previous session. Do not immediately flush in this case
+      // to avoid capturing only the checkout and instead the replay will
+      // be captured if they perform any follow-up actions.
+      if (replay.session && replay.session.previousSessionId) {
+        return true;
+      }
+
+      // When in buffer mode, make sure we adjust the session started date to the current earliest event of the buffer
+      // this should usually be the timestamp of the checkout event, but to be safe...
+      if (replay.recordingMode === 'buffer' && replay.session && replay.eventBuffer) {
+        const earliestEvent = replay.eventBuffer.getEarliestTimestamp();
+        if (earliestEvent) {
+          replay.session.started = earliestEvent;
+
+          if (replay.getOptions().stickySession) {
+            saveSession(replay.session);
           }
         }
+      }
 
-        if (replay.recordingMode === 'session') {
-          // If the full snapshot is due to an initial load, we will not have
-          // a previous session ID. In this case, we want to buffer events
-          // for a set amount of time before flushing. This can help avoid
-          // capturing replays of users that immediately close the window.
-          void replay.flush();
-        }
+      if (replay.recordingMode === 'session') {
+        // If the full snapshot is due to an initial load, we will not have
+        // a previous session ID. In this case, we want to buffer events
+        // for a set amount of time before flushing. This can help avoid
+        // capturing replays of users that immediately close the window.
+        void replay.flush();
+      }
 
-        return true;
-      });
+      return true;
     });
   };
 }
@@ -6635,26 +6665,6 @@ function addSettingsEvent(replay, isCheckout) {
   return addEvent(replay, createOptionsEvent(replay), false);
 }
 
-/**
- * Sample a session based on the provided sample rates.
- */
-function sampleSession({
-  errorSampleRate,
-  sessionSampleRate,
-}
-
-) {
-  if (errorSampleRate <= 0 && sessionSampleRate <= 0) {
-    return false;
-  }
-
-  if (isSampled(sessionSampleRate)) {
-    return 'session';
-  }
-
-  return errorSampleRate > 0 ? 'buffer' : false;
-}
-
 /**
  * Create a replay envelope ready to be sent.
  * This includes both the replay event, as well as the recording data.
@@ -7046,6 +7056,7 @@ class ReplayContainer  {
    */
     __init4() {this.timeouts = {
     sessionIdlePause: SESSION_IDLE_PAUSE_DURATION,
+    sessionIdleExpire: SESSION_IDLE_EXPIRE_DURATION,
     maxSessionLife: MAX_SESSION_LIFE,
   }; }
 
@@ -7057,30 +7068,35 @@ class ReplayContainer  {
 
    __init6() {this._flushLock = null;}
 
+  /**
+   * Timestamp of the last user activity. This lives across sessions.
+   */
+   __init7() {this._lastActivity = Date.now();}
+
   /**
    * Is the integration currently active?
    */
-   __init7() {this._isEnabled = false;}
+   __init8() {this._isEnabled = false;}
 
   /**
    * Paused is a state where:
    * - DOM Recording is not listening at all
    * - Nothing will be added to event buffer (e.g. core SDK events)
    */
-   __init8() {this._isPaused = false;}
+   __init9() {this._isPaused = false;}
 
   /**
    * Have we attached listeners to the core SDK?
    * Note we have to track this as there is no way to remove instrumentation handlers.
    */
-   __init9() {this._hasInitializedCoreListeners = false;}
+   __init10() {this._hasInitializedCoreListeners = false;}
 
   /**
    * Function to stop recording
    */
-   __init10() {this._stopRecording = null;}
+   __init11() {this._stopRecording = null;}
 
-   __init11() {this._context = {
+   __init12() {this._context = {
     errorIds: new Set(),
     traceIds: new Set(),
     urls: [],
@@ -7093,7 +7109,7 @@ class ReplayContainer  {
     recordingOptions,
   }
 
-) {ReplayContainer.prototype.__init.call(this);ReplayContainer.prototype.__init2.call(this);ReplayContainer.prototype.__init3.call(this);ReplayContainer.prototype.__init4.call(this);ReplayContainer.prototype.__init5.call(this);ReplayContainer.prototype.__init6.call(this);ReplayContainer.prototype.__init7.call(this);ReplayContainer.prototype.__init8.call(this);ReplayContainer.prototype.__init9.call(this);ReplayContainer.prototype.__init10.call(this);ReplayContainer.prototype.__init11.call(this);ReplayContainer.prototype.__init12.call(this);ReplayContainer.prototype.__init13.call(this);ReplayContainer.prototype.__init14.call(this);ReplayContainer.prototype.__init15.call(this);ReplayContainer.prototype.__init16.call(this);ReplayContainer.prototype.__init17.call(this);
+) {ReplayContainer.prototype.__init.call(this);ReplayContainer.prototype.__init2.call(this);ReplayContainer.prototype.__init3.call(this);ReplayContainer.prototype.__init4.call(this);ReplayContainer.prototype.__init5.call(this);ReplayContainer.prototype.__init6.call(this);ReplayContainer.prototype.__init7.call(this);ReplayContainer.prototype.__init8.call(this);ReplayContainer.prototype.__init9.call(this);ReplayContainer.prototype.__init10.call(this);ReplayContainer.prototype.__init11.call(this);ReplayContainer.prototype.__init12.call(this);ReplayContainer.prototype.__init13.call(this);ReplayContainer.prototype.__init14.call(this);ReplayContainer.prototype.__init15.call(this);ReplayContainer.prototype.__init16.call(this);ReplayContainer.prototype.__init17.call(this);ReplayContainer.prototype.__init18.call(this);
     this._recordingOptions = recordingOptions;
     this._options = options;
 
@@ -7151,13 +7167,37 @@ class ReplayContainer  {
    */
    initializeSampling() {
     const { errorSampleRate, sessionSampleRate } = this._options;
-    const sampled = sampleSession({ errorSampleRate, sessionSampleRate });
 
-    if (!sampled) {
+    // If neither sample rate is > 0, then do nothing - user will need to call one of
+    // `start()` or `startBuffering` themselves.
+    if (errorSampleRate <= 0 && sessionSampleRate <= 0) {
+      return;
+    }
+
+    // Otherwise if there is _any_ sample rate set, try to load an existing
+    // session, or create a new one.
+    const isSessionSampled = this._loadAndCheckSession();
+
+    if (!isSessionSampled) {
+      // This should only occur if `errorSampleRate` is 0 and was unsampled for
+      // session-based replay. In this case there is nothing to do.
+      return;
+    }
+
+    if (!this.session) {
+      // This should not happen, something wrong has occurred
+      this._handleException(new Error('Unable to initialize and create session'));
       return;
     }
 
-    this._initializeSession(sampled);
+    if (this.session.sampled && this.session.sampled !== 'session') {
+      // If not sampled as session-based, then recording mode will be `buffer`
+      // Note that we don't explicitly check if `sampled === 'buffer'` because we
+      // could have sessions from Session storage that are still `error` from
+      // prior SDK version.
+      this.recordingMode = 'buffer';
+    }
+
     this._initializeRecording();
   }
 
@@ -7177,7 +7217,20 @@ class ReplayContainer  {
       throw new Error('Replay buffering is in progress, call `flush()` to save the replay');
     }
 
-    this._initializeSession('session', { forceSampled: true });
+    const previousSessionId = this.session && this.session.id;
+
+    const { session } = getSession({
+      timeouts: this.timeouts,
+      stickySession: Boolean(this._options.stickySession),
+      currentSession: this.session,
+      // This is intentional: create a new session-based replay when calling `start()`
+      sessionSampleRate: 1,
+      allowBuffering: false,
+    });
+
+    session.previousSessionId = previousSessionId;
+    this.session = session;
+
     this._initializeRecording();
   }
 
@@ -7190,7 +7243,20 @@ class ReplayContainer  {
       throw new Error('Replay recording is already in progress');
     }
 
-    this._initializeSession('buffer', { forceSampled: true });
+    const previousSessionId = this.session && this.session.id;
+
+    const { session } = getSession({
+      timeouts: this.timeouts,
+      stickySession: Boolean(this._options.stickySession),
+      currentSession: this.session,
+      sessionSampleRate: 0,
+      allowBuffering: true,
+    });
+
+    session.previousSessionId = previousSessionId;
+    this.session = session;
+
+    this.recordingMode = 'buffer';
     this._initializeRecording();
   }
 
@@ -7272,7 +7338,8 @@ class ReplayContainer  {
       this.eventBuffer && this.eventBuffer.destroy();
       this.eventBuffer = null;
 
-      // Clear session from session storage
+      // Clear session from session storage, note this means if a new session
+      // is started after, it will not have `previousSessionId`
       clearSession(this);
     } catch (err) {
       this._handleException(err);
@@ -7285,10 +7352,6 @@ class ReplayContainer  {
    * not as thorough of a shutdown as `stop()`.
    */
    pause() {
-    if (this.isPaused()) {
-      return;
-    }
-
     this._isPaused = true;
     this.stopRecording();
   }
@@ -7300,14 +7363,12 @@ class ReplayContainer  {
    * new DOM checkout.`
    */
    resume() {
-    if (!this.isPaused()) {
+    if (!this._loadAndCheckSession()) {
       return;
     }
 
     this._isPaused = false;
-    this.checkSessionState(() => {
-      this.startRecording();
-    });
+    this.startRecording();
   }
 
   /**
@@ -7342,8 +7403,20 @@ class ReplayContainer  {
     // starting a new recording
     this.recordingMode = 'session';
 
+    // Once this session ends, we do not want to refresh it
     if (this.session) {
-      this.session.lastActivity = activityTime;
+      this.session.shouldRefresh = false;
+
+      // It's possible that the session lifespan is > max session lifespan
+      // because we have been buffering beyond max session lifespan (we ignore
+      // expiration given that `shouldRefresh` is true). Since we flip
+      // `shouldRefresh`, the session could be considered expired due to
+      // lifespan, which is not what we want. Update session start date to be
+      // the current timestamp, so that session is not considered to be
+      // expired. This means that max replay duration can be MAX_SESSION_LIFE +
+      // (length of buffer), which we are ok with.
+      this._updateUserActivity(activityTime);
+      this._updateSessionActivity(activityTime);
       this.session.started = activityTime;
       this._maybeSaveSession();
     }
@@ -7381,9 +7454,42 @@ class ReplayContainer  {
   }
 
   /**
-   * Updates the user activity timestamp.
+   * Updates the user activity timestamp and resumes recording. This should be
+   * called in an event handler for a user action that we consider as the user
+   * being "active" (e.g. a mouse click).
+   */
+   triggerUserActivity() {
+    this._updateUserActivity();
+
+    // This case means that recording was once stopped due to inactivity.
+    // Ensure that recording is resumed.
+    if (!this._stopRecording) {
+      // Create a new session, otherwise when the user action is flushed, it
+      // will get rejected due to an expired session.
+      if (!this._loadAndCheckSession()) {
+        return;
+      }
+
+      // Note: This will cause a new DOM checkout
+      this.resume();
+      return;
+    }
+
+    // Otherwise... recording was never suspended, continue as normalish
+    this.checkAndHandleExpiredSession();
+
+    this._updateSessionActivity();
+  }
+
+  /**
+   * Updates the user activity timestamp *without* resuming
+   * recording. Some user events (e.g. keydown) can be create
+   * low-value replays that only contain the keypress as a
+   * breadcrumb. Instead this would require other events to
+   * create a new replay after a session has expired.
    */
    updateUserActivity() {
+    this._updateUserActivity();
     this._updateSessionActivity();
   }
 
@@ -7428,6 +7534,54 @@ class ReplayContainer  {
     return this.session && this.session.id;
   }
 
+  /**
+   * Checks if recording should be stopped due to user inactivity. Otherwise
+   * check if session is expired and create a new session if so. Triggers a new
+   * full snapshot on new session.
+   *
+   * Returns true if session is not expired, false otherwise.
+   * @hidden
+   */
+   checkAndHandleExpiredSession() {
+    const oldSessionId = this.getSessionId();
+
+    // Prevent starting a new session if the last user activity is older than
+    // SESSION_IDLE_PAUSE_DURATION. Otherwise non-user activity can trigger a new
+    // session+recording. This creates noisy replays that do not have much
+    // content in them.
+    if (
+      this._lastActivity &&
+      isExpired(this._lastActivity, this.timeouts.sessionIdlePause) &&
+      this.session &&
+      this.session.sampled === 'session'
+    ) {
+      // Pause recording only for session-based replays. Otherwise, resuming
+      // will create a new replay and will conflict with users who only choose
+      // to record error-based replays only. (e.g. the resumed replay will not
+      // contain a reference to an error)
+      this.pause();
+      return;
+    }
+
+    // --- There is recent user activity --- //
+    // This will create a new session if expired, based on expiry length
+    if (!this._loadAndCheckSession()) {
+      return;
+    }
+
+    // Session was expired if session ids do not match
+    const expired = oldSessionId !== this.getSessionId();
+
+    if (!expired) {
+      return true;
+    }
+
+    // Session is expired, trigger a full snapshot (which will create a new session)
+    this._triggerFullSnapshot();
+
+    return false;
+  }
+
   /**
    * Capture some initial state that can change throughout the lifespan of the
    * replay. This is required because otherwise they would be captured at the
@@ -7480,23 +7634,6 @@ class ReplayContainer  {
     return res;
   }
 
-  /**
-   * Check the state/expiration of the session.
-   * The callback is called when the session is neither paused nor expired.
-   */
-   checkSessionState(onContinue) {
-    if (!this.session || !this.session.sampled) {
-      return;
-    }
-
-    checkSessionState(this.session, this.recordingMode, this.timeouts, {
-      onPause: () => this.pause(),
-      ensureResumed: () => this.resume(),
-      onEnd: () => this._refreshSession(),
-      onContinue,
-    });
-  }
-
   /**
    * This will get the parametrized route name of the current page.
    * This is only available if performance is enabled, and if an instrumented router is used.
@@ -7510,31 +7647,6 @@ class ReplayContainer  {
     return lastTransaction.name;
   }
 
-  /**
-   * Initialize a new session.
-   */
-   _initializeSession(sampled, { forceSampled = false } = {}) {
-    const { stickySession } = this._options;
-
-    // If neither sample rate is > 0, then do nothing - user will need to call one of
-    // `start()` or `startBuffering` themselves.
-    if (!sampled) {
-      return;
-    }
-
-    const session = restoreOrCreateSession({ stickySession, sampled, forceSampled });
-
-    // This shouldn't be possible really, but just in case...
-    if (!session.sampled) {
-      return;
-    }
-
-    this.session = session;
-    this.recordingMode = this.session.sampled === 'buffer' ? 'buffer' : 'session';
-
-    return;
-  }
-
   /**
    * Initialize and start all listeners to varying events (DOM,
    * Performance Observer, Recording, Sentry SDK, etc)
@@ -7544,7 +7656,7 @@ class ReplayContainer  {
 
     // this method is generally called on page load or manually - in both cases
     // we should treat it as an activity
-    this.updateUserActivity();
+    this._updateSessionActivity();
 
     this.eventBuffer = createEventBuffer({
       useCompression: this._options.useCompression,
@@ -7555,7 +7667,6 @@ class ReplayContainer  {
 
     // Need to set as enabled before we start recording, as `record()` can trigger a flush with a new checkout
     this._isEnabled = true;
-    this._isPaused = false;
 
     this.startRecording();
   }
@@ -7570,31 +7681,37 @@ class ReplayContainer  {
   }
 
   /**
-   * Refresh a session that has ended, either when it exceeded the max. age or when it was inactive for too long.
-   * This means there was a sampled & sent session before - this will never be called while the session is buffering.
+   * Loads (or refreshes) the current session.
+   * Returns false if session is not recorded.
    */
-   _refreshSession() {
-    // To avoid firing this multiple times, we check if we are even recording
-    if (!this.isEnabled()) {
-      return;
+   _loadAndCheckSession() {
+    const { type, session } = getSession({
+      timeouts: this.timeouts,
+      stickySession: Boolean(this._options.stickySession),
+      currentSession: this.session,
+      sessionSampleRate: this._options.sessionSampleRate,
+      allowBuffering: this._options.errorSampleRate > 0 || this.recordingMode === 'buffer',
+    });
+
+    // If session was newly created (i.e. was not loaded from storage), then
+    // enable flag to create the root replay
+    if (type === 'new') {
+      this.setInitialState();
     }
 
-    const { errorSampleRate, sessionSampleRate } = this._options;
-    const sampled = sampleSession({ errorSampleRate, sessionSampleRate });
+    const currentSessionId = this.getSessionId();
+    if (session.id !== currentSessionId) {
+      session.previousSessionId = currentSessionId;
+    }
 
-    if (!sampled || !this.session) {
-      void this.stop('session expired without new session');
-      return;
+    this.session = session;
+
+    if (!this.session.sampled) {
+      void this.stop('session unsampled');
+      return false;
     }
 
-    void this.stop('session expired with refreshing').then(() => {
-      if (sampled === 'session') {
-        return this.start();
-      }
-      if (sampled === 'buffer') {
-        return this.startBuffering();
-      }
-    });
+    return true;
   }
 
   /**
@@ -7659,7 +7776,7 @@ class ReplayContainer  {
    * be hidden. Likewise, moving a different window to cover the contents of the
    * page will also trigger a change to a hidden state.
    */
-   __init12() {this._handleVisibilityChange = () => {
+   __init13() {this._handleVisibilityChange = () => {
     if (WINDOW.document.visibilityState === 'visible') {
       this._doChangeToForegroundTasks();
     } else {
@@ -7670,7 +7787,7 @@ class ReplayContainer  {
   /**
    * Handle when page is blurred
    */
-   __init13() {this._handleWindowBlur = () => {
+   __init14() {this._handleWindowBlur = () => {
     const breadcrumb = createBreadcrumb({
       category: 'ui.blur',
     });
@@ -7683,7 +7800,7 @@ class ReplayContainer  {
   /**
    * Handle when page is focused
    */
-   __init14() {this._handleWindowFocus = () => {
+   __init15() {this._handleWindowFocus = () => {
     const breadcrumb = createBreadcrumb({
       category: 'ui.focus',
     });
@@ -7694,7 +7811,7 @@ class ReplayContainer  {
   };}
 
   /** Ensure page remains active when a key is pressed. */
-   __init15() {this._handleKeyboardEvent = (event) => {
+   __init16() {this._handleKeyboardEvent = (event) => {
     handleKeyboardEvent(this, event);
   };}
 
@@ -7702,35 +7819,71 @@ class ReplayContainer  {
    * Tasks to run when we consider a page to be hidden (via blurring and/or visibility)
    */
    _doChangeToBackgroundTasks(breadcrumb) {
-    this.checkSessionState(() => {
-      if (breadcrumb) {
-        this._createCustomBreadcrumb(breadcrumb);
-      }
+    if (!this.session) {
+      return;
+    }
 
-      // Send replay when the page/tab becomes hidden. There is no reason to send
-      // replay if it becomes visible, since no actions we care about were done
-      // while it was hidden
-      void this.conditionalFlush();
-    });
+    const expired = isSessionExpired(this.session, this.timeouts);
+
+    if (breadcrumb && !expired) {
+      this._createCustomBreadcrumb(breadcrumb);
+    }
+
+    // Send replay when the page/tab becomes hidden. There is no reason to send
+    // replay if it becomes visible, since no actions we care about were done
+    // while it was hidden
+    void this.conditionalFlush();
   }
 
   /**
    * Tasks to run when we consider a page to be visible (via focus and/or visibility)
    */
    _doChangeToForegroundTasks(breadcrumb) {
-    this.checkSessionState(() => {
-      if (breadcrumb) {
-        this._createCustomBreadcrumb(breadcrumb);
-      }
-    });
+    if (!this.session) {
+      return;
+    }
+
+    const isSessionActive = this.checkAndHandleExpiredSession();
+
+    if (!isSessionActive) {
+      // If the user has come back to the page within SESSION_IDLE_PAUSE_DURATION
+      // ms, we will re-use the existing session, otherwise create a new
+      // session
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log('[Replay] Document has become active, but session has expired');
+      return;
+    }
+
+    if (breadcrumb) {
+      this._createCustomBreadcrumb(breadcrumb);
+    }
+  }
+
+  /**
+   * Trigger rrweb to take a full snapshot which will cause this plugin to
+   * create a new Replay event.
+   */
+   _triggerFullSnapshot(checkout = true) {
+    try {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log('[Replay] Taking full rrweb snapshot');
+      record.takeFullSnapshot(checkout);
+    } catch (err) {
+      this._handleException(err);
+    }
+  }
+
+  /**
+   * Update user activity (across session lifespans)
+   */
+   _updateUserActivity(_lastActivity = Date.now()) {
+    this._lastActivity = _lastActivity;
   }
 
   /**
    * Updates the session's last activity timestamp
    */
-   _updateSessionActivity(lastActivity = Date.now()) {
+   _updateSessionActivity(_lastActivity = Date.now()) {
     if (this.session) {
-      this.session.lastActivity = lastActivity;
+      this.session.lastActivity = _lastActivity;
       this._maybeSaveSession();
     }
   }
@@ -7881,7 +8034,7 @@ class ReplayContainer  {
    * Flush recording data to Sentry. Creates a lock so that only a single flush
    * can be active at a time. Do not call this directly.
    */
-   __init16() {this._flush = async ({
+   __init17() {this._flush = async ({
     force = false,
   }
 
@@ -7891,58 +8044,42 @@ class ReplayContainer  {
       return;
     }
 
-    return new Promise(resolve => {
-      if (!this.session) {
-        resolve();
-        return;
-      }
-      checkSessionState(this.session, this.recordingMode, this.timeouts, {
-        onPause: () => {
-          this.pause();
-          resolve();
-        },
-        ensureResumed: () => this.resume(),
-        onEnd: () => {
-          (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error('[Replay] Attempting to finish replay event after session expired.');
-          this._refreshSession();
-          resolve();
-        },
-        onContinue: () => {
-          void this._flushLocked().then(resolve);
-        },
-      });
-    });
-  };}
+    if (!this.checkAndHandleExpiredSession()) {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error('[Replay] Attempting to finish replay event after session expired.');
+      return;
+    }
 
-  /**
-   * Flush, while locking so any future flush attemps while this is ongoing are queued.
-   */
-   async _flushLocked() {
-    try {
-      // A flush is about to happen, cancel any queued flushes
-      this._debouncedFlush.cancel();
+    if (!this.session) {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error('[Replay] No session found to flush.');
+      return;
+    }
 
-      // this._flushLock acts as a lock so that future calls to `_flush()`
-      // will be blocked until this promise resolves
-      if (!this._flushLock) {
-        this._flushLock = this._runFlush();
-        await this._flushLock;
-        this._flushLock = null;
-        return;
-      }
+    // A flush is about to happen, cancel any queued flushes
+    this._debouncedFlush.cancel();
 
-      // Wait for previous flush to finish, then call the debounced `_flush()`.
-      // It's possible there are other flush requests queued and waiting for it
-      // to resolve. We want to reduce all outstanding requests (as well as any
-      // new flush requests that occur within a second of the locked flush
-      // completing) into a single flush.
+    // this._flushLock acts as a lock so that future calls to `_flush()`
+    // will be blocked until this promise resolves
+    if (!this._flushLock) {
+      this._flushLock = this._runFlush();
       await this._flushLock;
-    } catch (error) {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error(error);
+      this._flushLock = null;
+      return;
     }
 
-    this._debouncedFlush();
-  }
+    // Wait for previous flush to finish, then call the debounced `_flush()`.
+    // It's possible there are other flush requests queued and waiting for it
+    // to resolve. We want to reduce all outstanding requests (as well as any
+    // new flush requests that occur within a second of the locked flush
+    // completing) into a single flush.
+
+    try {
+      await this._flushLock;
+    } catch (err) {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error(err);
+    } finally {
+      this._debouncedFlush();
+    }
+  };}
 
   /** Save the session, if it is sticky */
    _maybeSaveSession() {
@@ -7952,7 +8089,7 @@ class ReplayContainer  {
   }
 
   /** Handler for rrweb.record.onMutation */
-   __init17() {this._onMutationHandler = (mutations) => {
+   __init18() {this._onMutationHandler = (mutations) => {
     const count = mutations.length;
 
     const mutationLimit = this._options.mutationLimit;