feat(replay): Allow skipping the final flush on stop() via { flush: false }

The public `ReplayIntegration.stop()` always force-flushes the pending
segment when recording in `session` mode, with no way to opt out. Since
Replay envelopes bypass `beforeSend`, consent-gated setups that call
`stop()` on consent withdrawal end up sending the buffered segment after
the user revoked consent.

Expose the existing internal `forceFlush` control on the public API as
`stop({ flush?: boolean })`. It defaults to the current behavior
(flush when `recordingMode === 'session'`), so the change is fully
backwards compatible. `flush: false` stops recording without sending the
pending segment.

Closes #22220

Author: trinitiwowka

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+- feat(replay): Allow skipping the final flush when stopping recording via `stop({ flush: false })` ([#PR_NUMBER](https://github.com/getsentry/sentry-javascript/pull/PR_NUMBER))
+
 Work in this release was contributed by @dobladov and @PeterWadie. Thank you for your contributions!
 
 ## 10.65.0

packages/replay-internal/src/integration.ts

@@ -298,13 +298,25 @@ export class Replay implements Integration {
   /**
    * Currently, this needs to be manually called (e.g. for tests). Sentry SDK
    * does not support a teardown
+   *
+   * @param options.flush - Whether to flush the pending replay segment when stopping.
+   * When recording in `session` mode, `stop()` flushes the buffered-but-unsent segment by
+   * default (`flush: true`), matching the previous behavior. Pass `flush: false` to stop
+   * recording without sending that pending segment — useful when a user withdraws consent
+   * and no further data should leave the browser.
+   *
+   * Note: `flush: false` only prevents the *pending* (final) segment from being sent. It does
+   * **not** retract segments that were already sent earlier during `session` recording.
    */
-  public stop(): Promise<void> {
+  public stop(options?: { flush?: boolean }): Promise<void> {
     if (!this._replay) {
       return Promise.resolve();
     }
 
-    return this._replay.stop({ forceFlush: this._replay.recordingMode === 'session', reason: 'manual' });
+    return this._replay.stop({
+      forceFlush: options?.flush ?? this._replay.recordingMode === 'session',
+      reason: 'manual',
+    });
   }
 
   /**

packages/replay-internal/test/integration/stop.test.ts

@@ -153,6 +153,45 @@ describe('Integration | stop', () => {
     });
   });
 
+  it('does not flush the pending segment when stopped with `{ flush: false }` in session mode', async function () {
+    // Default mock SDK records in `session` mode (replaysSessionSampleRate: 1.0)
+    expect(replay.recordingMode).toBe('session');
+
+    const TEST_EVENT = getTestEventIncremental({ timestamp: BASE_TIMESTAMP });
+    addEvent(replay, TEST_EVENT, true);
+    expect(replay.eventBuffer?.hasEvents).toBe(true);
+    expect(mockRunFlush).toHaveBeenCalledTimes(0);
+
+    // stop without force-flushing the pending segment (e.g. on consent withdrawal)
+    await integration.stop({ flush: false });
+
+    // the buffered segment must not have been flushed/sent
+    expect(mockRunFlush).toHaveBeenCalledTimes(0);
+    expect(replay).not.toHaveLastSentReplay();
+
+    // recording is still torn down as usual
+    expect(replay.eventBuffer).toBe(null);
+    expect(replay.session).toEqual(undefined);
+  });
+
+  it('flushes the pending segment when stopped with `{ flush: true }` in session mode', async function () {
+    expect(replay.recordingMode).toBe('session');
+
+    const TEST_EVENT = getTestEventIncremental({ timestamp: BASE_TIMESTAMP });
+    addEvent(replay, TEST_EVENT, true);
+    expect(replay.eventBuffer?.hasEvents).toBe(true);
+    expect(mockRunFlush).toHaveBeenCalledTimes(0);
+
+    // explicitly force-flush the pending segment
+    await integration.stop({ flush: true });
+
+    expect(mockRunFlush).toHaveBeenCalledTimes(1);
+    expect(replay.eventBuffer).toBe(null);
+    expect(replay).toHaveLastSentReplay({
+      recordingData: JSON.stringify([TEST_EVENT]),
+    });
+  });
+
   it('does not call core SDK `addClickKeypressInstrumentationHandler` after initial setup', async function () {
     // NOTE: We clear mockAddDomInstrumentationHandler after every test
     await integration.stop();