@sentry/replay 7.67.0 → 7.68.0

package/types-ts3.8/replay.d.ts

@@ -0,0 +1,308 @@
+import { ReplayRecordingMode, Transaction } from '@sentry/types';
+import { ClickDetector } from './coreHandlers/handleClick';
+import { AddEventResult, AddUpdateCallback, AllPerformanceEntry, EventBuffer, InternalEventContext, RecordingEvent, RecordingOptions, ReplayContainer as ReplayContainerInterface, ReplayPluginOptions, SendBufferedReplayOptions, Session, Timeouts } from './types';
+import { SKIPPED } from './util/throttle';
+import { THROTTLED } from './util/throttle';
+/**
+ * The main replay container class, which holds all the state and methods for recording and sending replays.
+ */
+export declare class ReplayContainer implements ReplayContainerInterface {
+    eventBuffer: EventBuffer | null;
+    /**
+     * List of PerformanceEntry from PerformanceObserver
+     */
+    performanceEvents: AllPerformanceEntry[];
+    session: Session | undefined;
+    clickDetector: ClickDetector | undefined;
+    /**
+     * Recording can happen in one of three modes:
+     *   - session: Record the whole session, sending it continuously
+     *   - buffer: Always keep the last 60s of recording, requires:
+     *     - having replaysOnErrorSampleRate > 0 to capture replay when an error occurs
+     *     - or calling `flush()` to send the replay
+     */
+    recordingMode: ReplayRecordingMode;
+    /**
+     * The current or last active transcation.
+     * This is only available when performance is enabled.
+     */
+    lastTransaction?: Transaction;
+    /**
+     * These are here so we can overwrite them in tests etc.
+     * @hidden
+     */
+    readonly timeouts: Timeouts;
+    private _throttledAddEvent;
+    /**
+     * Options to pass to `rrweb.record()`
+     */
+    private readonly _recordingOptions;
+    private readonly _options;
+    private _performanceObserver;
+    private _debouncedFlush;
+    private _flushLock;
+    /**
+     * Timestamp of the last user activity. This lives across sessions.
+     */
+    private _lastActivity;
+    /**
+     * Is the integration currently active?
+     */
+    private _isEnabled;
+    /**
+     * Paused is a state where:
+     * - DOM Recording is not listening at all
+     * - Nothing will be added to event buffer (e.g. core SDK events)
+     */
+    private _isPaused;
+    /**
+     * Have we attached listeners to the core SDK?
+     * Note we have to track this as there is no way to remove instrumentation handlers.
+     */
+    private _hasInitializedCoreListeners;
+    /**
+     * Function to stop recording
+     */
+    private _stopRecording;
+    private _context;
+    constructor({ options, recordingOptions, }: {
+        options: ReplayPluginOptions;
+        recordingOptions: RecordingOptions;
+    });
+    /** Get the event context. */
+    getContext(): InternalEventContext;
+    /** If recording is currently enabled. */
+    isEnabled(): boolean;
+    /** If recording is currently paused. */
+    isPaused(): boolean;
+    /** Get the replay integration options. */
+    getOptions(): ReplayPluginOptions;
+    /**
+     * Initializes the plugin based on sampling configuration. Should not be
+     * called outside of constructor.
+     */
+    initializeSampling(): void;
+    /**
+     * Start a replay regardless of sampling rate. Calling this will always
+     * create a new session. Will throw an error if replay is already in progress.
+     *
+     * Creates or loads a session, attaches listeners to varying events (DOM,
+     * _performanceObserver, Recording, Sentry SDK, etc)
+     */
+    start(): void;
+    /**
+     * Start replay buffering. Buffers until `flush()` is called or, if
+     * `replaysOnErrorSampleRate` > 0, an error occurs.
+     */
+    startBuffering(): void;
+    /**
+     * Start recording.
+     *
+     * Note that this will cause a new DOM checkout
+     */
+    startRecording(): void;
+    /**
+     * Stops the recording, if it was running.
+     *
+     * Returns true if it was previously stopped, or is now stopped,
+     * otherwise false.
+     */
+    stopRecording(): boolean;
+    /**
+     * Currently, this needs to be manually called (e.g. for tests). Sentry SDK
+     * does not support a teardown
+     */
+    stop({ forceFlush, reason }?: {
+        forceFlush?: boolean;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Pause some replay functionality. See comments for `_isPaused`.
+     * This differs from stop as this only stops DOM recording, it is
+     * not as thorough of a shutdown as `stop()`.
+     */
+    pause(): void;
+    /**
+     * Resumes recording, see notes for `pause().
+     *
+     * Note that calling `startRecording()` here will cause a
+     * new DOM checkout.`
+     */
+    resume(): void;
+    /**
+     * If not in "session" recording mode, flush event buffer which will create a new replay.
+     * Unless `continueRecording` is false, the replay will continue to record and
+     * behave as a "session"-based replay.
+     *
+     * Otherwise, queue up a flush.
+     */
+    sendBufferedReplayOrFlush({ continueRecording }?: SendBufferedReplayOptions): Promise<void>;
+    /**
+     * We want to batch uploads of replay events. Save events only if
+     * `<flushMinDelay>` milliseconds have elapsed since the last event
+     * *OR* if `<flushMaxDelay>` milliseconds have elapsed.
+     *
+     * Accepts a callback to perform side-effects and returns true to stop batch
+     * processing and hand back control to caller.
+     */
+    addUpdate(cb: AddUpdateCallback): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * Only flush if `this.recordingMode === 'session'`
+     */
+    conditionalFlush(): Promise<void>;
+    /**
+     * Flush using debounce flush
+     */
+    flush(): Promise<void>;
+    /**
+     * Always flush via `_debouncedFlush` so that we do not have flushes triggered
+     * from calling both `flush` and `_debouncedFlush`. Otherwise, there could be
+     * cases of mulitple flushes happening closely together.
+     */
+    flushImmediate(): Promise<void>;
+    /**
+     * Cancels queued up flushes.
+     */
+    cancelFlush(): void;
+    /** Get the current sesion (=replay) ID */
+    getSessionId(): string | undefined;
+    /**
+     * 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(): boolean | void;
+    /**
+     * Capture some initial state that can change throughout the lifespan of the
+     * replay. This is required because otherwise they would be captured at the
+     * first flush.
+     */
+    setInitialState(): void;
+    /**
+     * Add a breadcrumb event, that may be throttled.
+     * If it was throttled, we add a custom breadcrumb to indicate that.
+     */
+    throttledAddEvent(event: RecordingEvent, isCheckout?: boolean): typeof THROTTLED | typeof SKIPPED | Promise<AddEventResult | null>;
+    /**
+     * 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.
+     */
+    getCurrentRoute(): string | undefined;
+    /**
+     * Initialize and start all listeners to varying events (DOM,
+     * Performance Observer, Recording, Sentry SDK, etc)
+     */
+    private _initializeRecording;
+    /** A wrapper to conditionally capture exceptions. */
+    private _handleException;
+    /**
+     * Loads (or refreshes) the current session.
+     */
+    private _initializeSessionForSampling;
+    /**
+     * Checks and potentially refreshes the current session.
+     * Returns false if session is not recorded.
+     */
+    private _checkSession;
+    /**
+     * Adds listeners to record events for the replay
+     */
+    private _addListeners;
+    /**
+     * Cleans up listeners that were created in `_addListeners`
+     */
+    private _removeListeners;
+    /**
+     * Handle when visibility of the page content changes. Opening a new tab will
+     * cause the state to change to hidden because of content of current page will
+     * be hidden. Likewise, moving a different window to cover the contents of the
+     * page will also trigger a change to a hidden state.
+     */
+    private _handleVisibilityChange;
+    /**
+     * Handle when page is blurred
+     */
+    private _handleWindowBlur;
+    /**
+     * Handle when page is focused
+     */
+    private _handleWindowFocus;
+    /** Ensure page remains active when a key is pressed. */
+    private _handleKeyboardEvent;
+    /**
+     * Tasks to run when we consider a page to be hidden (via blurring and/or visibility)
+     */
+    private _doChangeToBackgroundTasks;
+    /**
+     * Tasks to run when we consider a page to be visible (via focus and/or visibility)
+     */
+    private _doChangeToForegroundTasks;
+    /**
+     * Trigger rrweb to take a full snapshot which will cause this plugin to
+     * create a new Replay event.
+     */
+    private _triggerFullSnapshot;
+    /**
+     * Update user activity (across session lifespans)
+     */
+    private _updateUserActivity;
+    /**
+     * Updates the session's last activity timestamp
+     */
+    private _updateSessionActivity;
+    /**
+     * Helper to create (and buffer) a replay breadcrumb from a core SDK breadcrumb
+     */
+    private _createCustomBreadcrumb;
+    /**
+     * Observed performance events are added to `this.performanceEvents`. These
+     * are included in the replay event before it is finished and sent to Sentry.
+     */
+    private _addPerformanceEntries;
+    /**
+     * Clear _context
+     */
+    private _clearContext;
+    /** Update the initial timestamp based on the buffer content. */
+    private _updateInitialTimestampFromEventBuffer;
+    /**
+     * Return and clear _context
+     */
+    private _popEventContext;
+    /**
+     * Flushes replay event buffer to Sentry.
+     *
+     * Performance events are only added right before flushing - this is
+     * due to the buffered performance observer events.
+     *
+     * Should never be called directly, only by `flush`
+     */
+    private _runFlush;
+    /**
+     * 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.
+     */
+    private _flush;
+    /** Save the session, if it is sticky */
+    private _maybeSaveSession;
+    /** Handler for rrweb.record.onMutation */
+    private _onMutationHandler;
+}
+//# sourceMappingURL=replay.d.ts.map

package/types-ts3.8/session/Session.d.ts

@@ -0,0 +1,8 @@
+import { Sampled, Session } from '../types';
+/**
+ * Get a session with defaults & applied sampling.
+ */
+export declare function makeSession(session: Partial<Session> & {
+    sampled: Sampled;
+}): Session;
+//# sourceMappingURL=Session.d.ts.map

package/types-ts3.8/session/clearSession.d.ts

@@ -0,0 +1,6 @@
+import { ReplayContainer } from '../../src/types';
+/**
+ * Removes the session from Session Storage and unsets session in replay instance
+ */
+export declare function clearSession(replay: ReplayContainer): void;
+//# sourceMappingURL=clearSession.d.ts.map

package/types-ts3.8/session/createSession.d.ts

@@ -0,0 +1,14 @@
+import { Sampled, Session, SessionOptions } from '../types';
+/**
+ * Get the sampled status for a session based on sample rates & current sampled status.
+ */
+export declare function getSessionSampleType(sessionSampleRate: number, allowBuffering: boolean): Sampled;
+/**
+ * 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".
+ */
+export declare function createSession({ sessionSampleRate, allowBuffering, stickySession }: SessionOptions, { previousSessionId }?: {
+    previousSessionId?: string;
+}): Session;
+//# sourceMappingURL=createSession.d.ts.map

package/types-ts3.8/session/fetchSession.d.ts

@@ -0,0 +1,6 @@
+import { Session } from '../types';
+/**
+ * Fetches a session from storage
+ */
+export declare function fetchSession(traceInternals?: boolean): Session | null;
+//# sourceMappingURL=fetchSession.d.ts.map

package/types-ts3.8/session/index.d.ts

@@ -0,0 +1,2 @@
+export * from './createSession';
+//# sourceMappingURL=index.d.ts.map

package/types-ts3.8/session/loadOrCreateSession.d.ts

@@ -0,0 +1,11 @@
+import { Session, SessionOptions } from '../types';
+/**
+ * Get or create a session, when initializing the replay.
+ * Returns a session that may be unsampled.
+ */
+export declare function loadOrCreateSession(currentSession: Session | undefined, { traceInternals, sessionIdleExpire, maxReplayDuration, }: {
+    sessionIdleExpire: number;
+    maxReplayDuration: number;
+    traceInternals?: boolean;
+}, sessionOptions: SessionOptions): Session;
+//# sourceMappingURL=loadOrCreateSession.d.ts.map

package/types-ts3.8/session/maybeRefreshSession.d.ts

@@ -0,0 +1,12 @@
+import { Session, SessionOptions } from '../types';
+/**
+ * Check a session, and either return it or a refreshed version of it.
+ * The refreshed version may be unsampled.
+ * You can check if the session has changed by comparing the session IDs.
+ */
+export declare function maybeRefreshSession(session: Session, { traceInternals, maxReplayDuration, sessionIdleExpire, }: {
+    sessionIdleExpire: number;
+    maxReplayDuration: number;
+    traceInternals?: boolean;
+}, sessionOptions: SessionOptions): Session;
+//# sourceMappingURL=maybeRefreshSession.d.ts.map

package/types-ts3.8/session/saveSession.d.ts

@@ -0,0 +1,6 @@
+import { Session } from '../types';
+/**
+ * Save a session to session storage.
+ */
+export declare function saveSession(session: Session): void;
+//# sourceMappingURL=saveSession.d.ts.map

package/types-ts3.8/types/deprecated.d.ts

@@ -0,0 +1,16 @@
+import { ReplayBreadcrumbFrame, ReplayBreadcrumbFrameEvent, ReplayEventType, ReplayEventWithTime, ReplayOptionFrameEvent, ReplaySpanFrame, ReplaySpanFrameEvent } from '.';
+/** @deprecated use ReplayEventType instead */
+export type EventType = ReplayEventType;
+/** @deprecated use ReplayEventWithTime instead */
+export type eventWithTime = ReplayEventWithTime;
+/** @deprecated use ReplayBreadcrumbFrame instead */
+export type BreadcrumbFrame = ReplayBreadcrumbFrame;
+/** @deprecated use ReplayBreadcrumbFrameEvent instead */
+export type BreadcrumbFrameEvent = ReplayBreadcrumbFrameEvent;
+/** @deprecated use ReplayOptionFrameEvent instead */
+export type OptionFrameEvent = ReplayOptionFrameEvent;
+/** @deprecated use ReplaySpanFrame instead */
+export type SpanFrame = ReplaySpanFrame;
+/** @deprecated use ReplaySpanFrameEvent instead */
+export type SpanFrameEvent = ReplaySpanFrameEvent;
+//# sourceMappingURL=deprecated.d.ts.map

package/types-ts3.8/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './performance';
+export * from './replay';
+export * from './replayFrame';
+export * from './request';
+export * from './rrweb';
+//# sourceMappingURL=index.d.ts.map

package/types-ts3.8/types/performance.d.ts

@@ -0,0 +1,124 @@
+import { ReplayNetworkRequestOrResponse } from './request';
+export type AllPerformanceEntry = PerformancePaintTiming | PerformanceResourceTiming | PerformanceNavigationTiming;
+export type PerformancePaintTiming = PerformanceEntry;
+export type PerformanceNavigationTiming = PerformanceEntry & PerformanceResourceTiming & {
+    type: string;
+    transferSize: number;
+    /**
+     * A DOMHighResTimeStamp representing the time immediately before the user agent
+     * sets the document's readyState to "interactive".
+     */
+    domInteractive: number;
+    /**
+     * A DOMHighResTimeStamp representing the time immediately before the current
+     * document's DOMContentLoaded event handler starts.
+     */
+    domContentLoadedEventStart: number;
+    /**
+     * A DOMHighResTimeStamp representing the time immediately after the current
+     * document's DOMContentLoaded event handler completes.
+     */
+    domContentLoadedEventEnd: number;
+    /**
+     * A DOMHighResTimeStamp representing the time immediately before the current
+     * document's load event handler starts.
+     */
+    loadEventStart: number;
+    /**
+     * A DOMHighResTimeStamp representing the time immediately after the current
+     * document's load event handler completes.
+     */
+    loadEventEnd: number;
+    /**
+     * A DOMHighResTimeStamp representing the time immediately before the user agent
+     * sets the document's readyState to "complete".
+     */
+    domComplete: number;
+    /**
+     * A number representing the number of redirects since the last non-redirect
+     * navigation in the current browsing context.
+     */
+    redirectCount: number;
+};
+export type ExperimentalPerformanceResourceTiming = PerformanceResourceTiming & {
+    responseStatus?: number;
+};
+export type PaintData = undefined;
+/**
+ * See https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming
+ *
+ * Note `navigation.push` will not have any data
+ */
+export type NavigationData = Partial<Pick<PerformanceNavigationTiming, 'decodedBodySize' | 'encodedBodySize' | 'duration' | 'domInteractive' | 'domContentLoadedEventEnd' | 'domContentLoadedEventStart' | 'loadEventStart' | 'loadEventEnd' | 'domComplete' | 'redirectCount'>> & {
+    /**
+     * Transfer size of resource
+     */
+    size?: number;
+};
+export type ResourceData = Pick<PerformanceResourceTiming, 'decodedBodySize' | 'encodedBodySize'> & {
+    /**
+     * Transfer size of resource
+     */
+    size: number;
+    /**
+     * HTTP status code. Note this is experimental and not available on all browsers.
+     */
+    statusCode?: number;
+};
+export interface LargestContentfulPaintData {
+    /**
+     * Render time (in ms) of the LCP
+     */
+    value: number;
+    size: number;
+    /**
+     * The recording id of the LCP node. -1 if not found
+     */
+    nodeId?: number;
+}
+/**
+ * Entries that come from window.performance
+ */
+export type AllPerformanceEntryData = PaintData | NavigationData | ResourceData | LargestContentfulPaintData;
+export interface MemoryData {
+    memory: {
+        jsHeapSizeLimit: number;
+        totalJSHeapSize: number;
+        usedJSHeapSize: number;
+    };
+}
+export interface NetworkRequestData {
+    method?: string;
+    statusCode?: number;
+    requestBodySize?: number;
+    responseBodySize?: number;
+    request?: ReplayNetworkRequestOrResponse;
+    response?: ReplayNetworkRequestOrResponse;
+}
+export interface HistoryData {
+    previous: string;
+}
+export type AllEntryData = AllPerformanceEntryData | MemoryData | NetworkRequestData | HistoryData;
+export interface ReplayPerformanceEntry<T> {
+    /**
+     * One of these types https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry/entryType
+     */
+    type: string;
+    /**
+     * A more specific description of the performance entry
+     */
+    name: string;
+    /**
+     * The start timestamp in seconds
+     */
+    start: number;
+    /**
+     * The end timestamp in seconds
+     */
+    end: number;
+    /**
+     * Additional unstructured data to be included
+     */
+    data: T;
+}
+//# sourceMappingURL=performance.d.ts.map