swetrix 4.2.0 → 4.4.0

package/dist/swetrix.cjs.js

@@ -90,13 +90,60 @@ const getPath = (options) => {
     return result;
 };
 
+const SESSION_REPLAY_PRIVACY_VALUES = ['total', 'normal', 'none'];
 const defaultActions = {
     stop() { },
 };
+const defaultSessionReplayActions = {
+    async stop() { },
+    async flush() { },
+};
 const DEFAULT_API_HOST = 'https://api.swetrix.com/log';
 const DEFAULT_API_BASE = 'https://api.swetrix.com';
+const DEFAULT_RRWEB_FILE = 'replaylibrary.min.js';
+const DEFAULT_RRWEB_URL = `https://cdn.jsdelivr.net/npm/swetrix@latest/dist/${DEFAULT_RRWEB_FILE}`;
+const DEFAULT_SESSION_REPLAY_FLUSH_INTERVAL = 5000;
+const DEFAULT_SESSION_REPLAY_MAX_EVENTS = 100;
+const DEFAULT_SESSION_REPLAY_MAX_CHUNK_BYTES = 512 * 1024;
+const DEFAULT_SESSION_REPLAY_MAX_EVENT_BYTES = 5 * 1024 * 1024;
+const DEFAULT_SESSION_REPLAY_MAX_DURATION_MS = 30 * 60 * 1000;
+const DEFAULT_SESSION_REPLAY_PRIVACY = 'total';
+const DEFAULT_SESSION_REPLAY_SAMPLING = {
+    mousemove: 50,
+    scroll: 150,
+    input: 'last',
+};
+const DEFAULT_SESSION_REPLAY_SLIM_DOM_OPTIONS = {
+    script: true,
+    comment: true,
+    headFavicon: true,
+    headWhitespace: true,
+    headMetaDescKeywords: true,
+    headMetaSocial: true,
+    headMetaRobots: true,
+    headMetaHttpEquiv: true,
+    headMetaAuthorship: true,
+    headMetaVerification: true,
+};
+const SESSION_REPLAY_ACTIVITY_EVENTS = [
+    'click',
+    'keydown',
+    'mousedown',
+    'mousemove',
+    'scroll',
+    'touchstart',
+];
 // Default cache duration: 5 minutes
 const DEFAULT_CACHE_DURATION = 5 * 60 * 1000;
+const getStringByteLength = (value) => {
+    if (typeof TextEncoder !== 'undefined') {
+        return new TextEncoder().encode(value).length;
+    }
+    if (typeof Blob !== 'undefined') {
+        return new Blob([value]).size;
+    }
+    return value.length;
+};
 class Lib {
     constructor(projectID, options) {
         this.projectID = projectID;
@@ -108,9 +155,15 @@ class Lib {
         this.activePage = null;
         this.errorListenerExists = false;
         this.cachedData = null;
+        this.rrwebLoader = null;
+        this.sessionReplayActions = null;
+        this.sessionReplayInitPromise = null;
         this.trackPathChange = this.trackPathChange.bind(this);
         this.heartbeat = this.heartbeat.bind(this);
         this.captureError = this.captureError.bind(this);
+        if (this.getSessionReplayPreloadOption()) {
+            void this.preloadSessionReplay().catch(() => undefined);
+        }
     }
     captureError(event) {
         var _a, _b, _c, _d;
@@ -258,10 +311,10 @@ class Lib {
         };
     }
     /**
-     * Fetches all feature flags and experiments for the project.
-     * Results are cached for 5 minutes by default.
+     * Fetches all feature flags for the project.
+     * Results are cached for 5 minutes by default and share a cache with experiments.
      *
-     * @param options - Options for evaluating feature flags.
+     * @param options - Options for evaluating feature flags (`profileId` only).
      * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
      * @returns A promise that resolves to a record of flag keys to boolean values.
      */
@@ -328,8 +381,8 @@ class Lib {
      * Gets the value of a single feature flag.
      *
      * @param key - The feature flag key.
-     * @param options - Options for evaluating the feature flag.
-     * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+     * @param options - Options for evaluating the feature flag (`profileId` only).
+     * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
      * @returns A promise that resolves to the boolean value of the flag.
      */
     async getFeatureFlag(key, options, defaultValue = false) {
@@ -344,16 +397,16 @@ class Lib {
         this.cachedData = null;
     }
     /**
-     * Fetches all A/B test experiments for the project.
+     * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
      * Results are cached for 5 minutes by default (shared cache with feature flags).
      *
-     * @param options - Options for evaluating experiments.
+     * @param options - Options for evaluating experiments (`profileId` only).
      * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
      * @returns A promise that resolves to a record of experiment IDs to variant keys.
      *
      * @example
      * ```typescript
-     * const experiments = await getExperiments()
+     * const experiments = await getExperiments({ profileId: 'user-123' })
      * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
      * ```
      */
@@ -384,13 +437,16 @@ class Lib {
      * Gets the variant key for a specific A/B test experiment.
      *
      * @param experimentId - The experiment ID.
-     * @param options - Options for evaluating the experiment.
-     * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+     * @param options - Options for evaluating the experiment (`profileId` only).
+     * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
      * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
      *
      * @example
      * ```typescript
-     * const variant = await getExperiment('checkout-redesign')
+     * const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })
+     *
+     * // Optional fallback variant:
+     * const variantWithFallback = await getExperiment('checkout-redesign', undefined, 'control')
      *
      * if (variant === 'new-checkout') {
      *   // Show new checkout flow
@@ -506,6 +562,196 @@ class Lib {
             return null;
         }
     }
+    async startSessionReplay(options = {}) {
+        if (this.sessionReplayActions) {
+            return this.sessionReplayActions;
+        }
+        if (this.sessionReplayInitPromise) {
+            return this.sessionReplayInitPromise;
+        }
+        const initPromise = this.initialiseSessionReplay(options);
+        this.sessionReplayInitPromise = initPromise;
+        try {
+            return await initPromise;
+        }
+        finally {
+            if (this.sessionReplayInitPromise === initPromise) {
+                this.sessionReplayInitPromise = null;
+            }
+        }
+    }
+    async initialiseSessionReplay(options) {
+        var _a;
+        if (this.sessionReplayActions) {
+            return this.sessionReplayActions;
+        }
+        if (!this.canTrack()) {
+            return defaultSessionReplayActions;
+        }
+        const maxDurationMs = typeof options.maxDurationMs === 'number' && options.maxDurationMs > 0
+            ? options.maxDurationMs
+            : DEFAULT_SESSION_REPLAY_MAX_DURATION_MS;
+        if (!this.shouldSampleSessionReplay(options.sampleRate)) {
+            return defaultSessionReplayActions;
+        }
+        try {
+            await this.preloadSessionReplay();
+        }
+        catch (_b) {
+            return defaultSessionReplayActions;
+        }
+        const rrweb = window.rrweb;
+        if (!(rrweb === null || rrweb === void 0 ? void 0 : rrweb.record)) {
+            return defaultSessionReplayActions;
+        }
+        const privacy = this.getSessionReplayPrivacy(options.privacy);
+        const proposedReplayId = this.createReplayId();
+        const started = await this.sendSessionReplayStart(proposedReplayId, privacy);
+        if (!started) {
+            return defaultSessionReplayActions;
+        }
+        const replayId = started.replayId;
+        const flushIntervalMs = typeof options.flushIntervalMs === 'number' && options.flushIntervalMs > 0
+            ? options.flushIntervalMs
+            : DEFAULT_SESSION_REPLAY_FLUSH_INTERVAL;
+        const maxEventsPerChunk = typeof options.maxEventsPerChunk === 'number' &&
+            options.maxEventsPerChunk > 0
+            ? Math.floor(options.maxEventsPerChunk)
+            : DEFAULT_SESSION_REPLAY_MAX_EVENTS;
+        const maxBytesPerChunkCandidate = typeof options.maxBytesPerChunk === 'number'
+            ? Math.floor(options.maxBytesPerChunk)
+            : Number.NaN;
+        const maxBytesPerChunk = maxBytesPerChunkCandidate >= 1
+            ? maxBytesPerChunkCandidate
+            : DEFAULT_SESSION_REPLAY_MAX_CHUNK_BYTES;
+        const maxBytesPerEventCandidate = typeof options.maxBytesPerEvent === 'number'
+            ? Math.floor(options.maxBytesPerEvent)
+            : Number.NaN;
+        const maxBytesPerEvent = maxBytesPerEventCandidate >= 1
+            ? maxBytesPerEventCandidate
+            : DEFAULT_SESSION_REPLAY_MAX_EVENT_BYTES;
+        const idleTimeoutMs = typeof options.idleTimeoutMs === 'number' && options.idleTimeoutMs > 0
+            ? options.idleTimeoutMs
+            : null;
+        let chunkIndex = started.nextChunkIndex;
+        let stopped = false;
+        let events = [];
+        let eventsByteLength = 0;
+        let flushing = Promise.resolve();
+        let maxDurationTimer;
+        let idleTimer;
+        const flush = async (useBeacon = false) => {
+            if (!events.length)
+                return;
+            const chunk = events;
+            events = [];
+            eventsByteLength = 0;
+            const currentChunkIndex = chunkIndex++;
+            flushing = flushing
+                .catch(() => undefined)
+                .then(() => this.sendSessionReplayChunk(replayId, privacy, currentChunkIndex, chunk, useBeacon));
+            await flushing;
+        };
+        const userEmit = (_a = options.rrweb) === null || _a === void 0 ? void 0 : _a.emit;
+        const recordOptions = this.getSessionReplayRecordOptions(privacy, options.rrweb, (event) => {
+            try {
+                userEmit === null || userEmit === void 0 ? void 0 : userEmit(event);
+            }
+            catch (_a) { }
+            let eventByteLength = 0;
+            try {
+                eventByteLength = getStringByteLength(JSON.stringify(event));
+            }
+            catch (_b) {
+                return;
+            }
+            if (eventByteLength > maxBytesPerEvent) {
+                return;
+            }
+            if (events.length &&
+                eventsByteLength + eventByteLength > maxBytesPerChunk) {
+                void flush();
+            }
+            events.push(event);
+            eventsByteLength += eventByteLength;
+            if (events.length >= maxEventsPerChunk ||
+                eventsByteLength >= maxBytesPerChunk) {
+                void flush();
+            }
+        }, Boolean(options.recordIframes), options.maskAllText);
+        const stopRecording = rrweb.record(recordOptions);
+        const timer = setInterval(() => void flush(), flushIntervalMs);
+        const flushOnPageExit = () => void flush(true);
+        const flushOnHidden = () => {
+            if (document.visibilityState === 'hidden') {
+                void flush(true);
+            }
+        };
+        const clearIdleTimer = () => {
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
+        };
+        const stopSessionReplay = async () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            if (maxDurationTimer) {
+                clearTimeout(maxDurationTimer);
+            }
+            clearIdleTimer();
+            window.removeEventListener('pagehide', flushOnPageExit);
+            document.removeEventListener('visibilitychange', flushOnHidden);
+            SESSION_REPLAY_ACTIVITY_EVENTS.forEach((eventName) => {
+                window.removeEventListener(eventName, resetIdleTimer);
+            });
+            stopRecording === null || stopRecording === void 0 ? void 0 : stopRecording();
+            await flush();
+            this.sessionReplayActions = null;
+            this.sessionReplayInitPromise = null;
+        };
+        const resetIdleTimer = () => {
+            if (!idleTimeoutMs || stopped)
+                return;
+            clearIdleTimer();
+            idleTimer = setTimeout(() => void stopSessionReplay(), idleTimeoutMs);
+        };
+        window.addEventListener('pagehide', flushOnPageExit);
+        document.addEventListener('visibilitychange', flushOnHidden);
+        maxDurationTimer = setTimeout(() => void stopSessionReplay(), maxDurationMs);
+        if (idleTimeoutMs) {
+            SESSION_REPLAY_ACTIVITY_EVENTS.forEach((eventName) => {
+                window.addEventListener(eventName, resetIdleTimer, { passive: true });
+            });
+            resetIdleTimer();
+        }
+        this.sessionReplayActions = {
+            stop: stopSessionReplay,
+            flush: async () => {
+                await flush();
+            },
+        };
+        return this.sessionReplayActions;
+    }
+    shouldSampleSessionReplay(sampleRate) {
+        if (typeof sampleRate !== 'number') {
+            return true;
+        }
+        if (sampleRate <= 0) {
+            return false;
+        }
+        if (sampleRate >= 1) {
+            return true;
+        }
+        return Math.random() < sampleRate;
+    }
+    getSessionReplayPrivacy(privacy) {
+        return SESSION_REPLAY_PRIVACY_VALUES.includes(privacy)
+            ? privacy
+            : DEFAULT_SESSION_REPLAY_PRIVACY;
+    }
     /**
      * Gets the API base URL (without /log suffix).
      */
@@ -595,6 +841,289 @@ class Lib {
         }
         return true;
     }
+    getSessionReplayUrl() {
+        const replayOption = this.getSessionReplayPreloadOption();
+        if (replayOption &&
+            typeof replayOption === 'object' &&
+            replayOption.rrwebUrl) {
+            return replayOption.rrwebUrl;
+        }
+        return this.getDefaultSessionReplayUrl();
+    }
+    getSessionReplayPreloadOption() {
+        var _a;
+        return (_a = this.options) === null || _a === void 0 ? void 0 : _a.preloadSessionReplay;
+    }
+    getDefaultSessionReplayUrl() {
+        if (!isInBrowser()) {
+            return DEFAULT_RRWEB_URL;
+        }
+        const trackerScript = this.getTrackerScript();
+        if (trackerScript === null || trackerScript === void 0 ? void 0 : trackerScript.src) {
+            const { hostname, pathname } = new URL(trackerScript.src);
+            if (hostname === 'swetrix.org' &&
+                /^\/swetrix(\.min)?\.js$/i.test(pathname)) {
+                return DEFAULT_RRWEB_URL;
+            }
+            return new URL(DEFAULT_RRWEB_FILE, trackerScript.src).toString();
+        }
+        return DEFAULT_RRWEB_URL;
+    }
+    getTrackerScript() {
+        const trackerScript = Array.from(document.scripts).find((script) => {
+            if (!script.src) {
+                return false;
+            }
+            try {
+                const { pathname } = new URL(script.src);
+                return /(^|\/)swetrix(\.min)?\.js$/i.test(pathname);
+            }
+            catch (_a) {
+                return false;
+            }
+        });
+        return trackerScript;
+    }
+    preloadSessionReplay() {
+        var _a;
+        if (!isInBrowser()) {
+            return Promise.resolve();
+        }
+        if ((_a = window.rrweb) === null || _a === void 0 ? void 0 : _a.record) {
+            return Promise.resolve();
+        }
+        if (this.rrwebLoader) {
+            return this.rrwebLoader;
+        }
+        if (window.__SWETRIX_RRWEB_LOADING__) {
+            this.rrwebLoader = window.__SWETRIX_RRWEB_LOADING__;
+            void this.rrwebLoader.catch(() => {
+                if (window.__SWETRIX_RRWEB_LOADING__ === this.rrwebLoader) {
+                    delete window.__SWETRIX_RRWEB_LOADING__;
+                }
+                this.rrwebLoader = null;
+            });
+            return this.rrwebLoader;
+        }
+        this.rrwebLoader = this.loadSessionReplayRecorder();
+        window.__SWETRIX_RRWEB_LOADING__ = this.rrwebLoader;
+        const loader = this.rrwebLoader;
+        void loader.catch(() => {
+            if (window.__SWETRIX_RRWEB_LOADING__ === loader) {
+                delete window.__SWETRIX_RRWEB_LOADING__;
+            }
+            if (this.rrwebLoader === loader) {
+                this.rrwebLoader = null;
+            }
+        });
+        return this.rrwebLoader;
+    }
+    async loadSessionReplayRecorder() {
+        const replayOption = this.getSessionReplayPreloadOption();
+        const hasCustomReplayUrl = replayOption && typeof replayOption === 'object' && replayOption.rrwebUrl;
+        if (hasCustomReplayUrl || this.getTrackerScript()) {
+            await this.loadSessionReplayScript(this.getSessionReplayUrl());
+            return;
+        }
+        if (await this.loadSessionReplayPackage()) {
+            return;
+        }
+        await this.loadSessionReplayScript(this.getDefaultSessionReplayUrl());
+    }
+    async loadSessionReplayPackage() {
+        try {
+            const rrwebModule = (await import('rrweb'));
+            const rrweb = rrwebModule.record ? rrwebModule : rrwebModule.default;
+            if (!(rrweb === null || rrweb === void 0 ? void 0 : rrweb.record)) {
+                return false;
+            }
+            window.rrweb = rrweb;
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+    loadSessionReplayScript(url) {
+        return new Promise((resolve, reject) => {
+            const script = document.createElement('script');
+            script.async = true;
+            script.src = url;
+            script.crossOrigin = 'anonymous';
+            script.onload = () => resolve();
+            script.onerror = () => reject(new Error('Failed to load rrweb'));
+            document.head.appendChild(script);
+        });
+    }
+    getSessionReplayRecordOptions(privacy, userOptions, emit, recordIframes, maskAllText) {
+        const hasUserSampling = userOptions &&
+            Object.prototype.hasOwnProperty.call(userOptions, 'sampling');
+        const hasUserSlimDOMOptions = userOptions &&
+            Object.prototype.hasOwnProperty.call(userOptions, 'slimDOMOptions');
+        const sampling = typeof (userOptions === null || userOptions === void 0 ? void 0 : userOptions.sampling) === 'object' && userOptions.sampling !== null
+            ? {
+                ...DEFAULT_SESSION_REPLAY_SAMPLING,
+                ...userOptions.sampling,
+            }
+            : hasUserSampling
+                ? userOptions === null || userOptions === void 0 ? void 0 : userOptions.sampling
+                : DEFAULT_SESSION_REPLAY_SAMPLING;
+        const slimDOMOptions = typeof (userOptions === null || userOptions === void 0 ? void 0 : userOptions.slimDOMOptions) === 'object' &&
+            userOptions.slimDOMOptions !== null
+            ? {
+                ...DEFAULT_SESSION_REPLAY_SLIM_DOM_OPTIONS,
+                ...userOptions.slimDOMOptions,
+            }
+            : hasUserSlimDOMOptions
+                ? userOptions === null || userOptions === void 0 ? void 0 : userOptions.slimDOMOptions
+                : DEFAULT_SESSION_REPLAY_SLIM_DOM_OPTIONS;
+        const options = {
+            recordCanvas: false,
+            recordCrossOriginIframes: false,
+            collectFonts: false,
+            inlineImages: false,
+            ...userOptions,
+            sampling,
+            slimDOMOptions,
+            emit,
+        };
+        const maskInputOptions = typeof options.maskInputOptions === 'object' &&
+            options.maskInputOptions !== null
+            ? options.maskInputOptions
+            : {};
+        const resolvedPrivacy = this.getSessionReplayPrivacy(privacy);
+        const defaultBlockSelector = recordIframes ? undefined : 'iframe';
+        const resolvedMaskAllText = typeof maskAllText === 'boolean'
+            ? maskAllText
+            : resolvedPrivacy === 'total';
+        const textMaskingOptions = resolvedMaskAllText
+            ? { maskTextSelector: '*' }
+            : {};
+        if (resolvedPrivacy === 'total') {
+            return {
+                ...options,
+                ...textMaskingOptions,
+                maskAllInputs: true,
+                blockSelector: this.mergeSelectors(this.mergeSelectors(options.blockSelector, defaultBlockSelector), 'img, picture, video, audio, canvas, svg'),
+                recordCanvas: false,
+                inlineImages: false,
+                emit,
+            };
+        }
+        if (resolvedPrivacy === 'normal') {
+            return {
+                ...options,
+                ...textMaskingOptions,
+                maskAllInputs: true,
+                blockSelector: this.mergeSelectors(options.blockSelector, defaultBlockSelector),
+                emit,
+            };
+        }
+        return {
+            ...options,
+            ...textMaskingOptions,
+            blockSelector: this.mergeSelectors(options.blockSelector, defaultBlockSelector),
+            maskInputOptions: {
+                ...maskInputOptions,
+                password: true,
+            },
+            emit,
+        };
+    }
+    mergeSelectors(existing, required) {
+        if (!required) {
+            return typeof existing === 'string' ? existing : undefined;
+        }
+        if (typeof existing === 'string' && existing.trim()) {
+            return `${existing}, ${required}`;
+        }
+        return required;
+    }
+    createReplayId() {
+        if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+            return crypto.randomUUID();
+        }
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    }
+    async sendSessionReplayStart(replayId, privacy) {
+        var _a, _b, _c;
+        try {
+            const apiBase = this.getApiBase();
+            const response = await fetch(`${apiBase}/log/session-replay/start`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    pid: this.projectID,
+                    replayId,
+                    privacy,
+                    pg: this.activePage ||
+                        getPath({
+                            hash: (_a = this.pageViewsOptions) === null || _a === void 0 ? void 0 : _a.hash,
+                            search: (_b = this.pageViewsOptions) === null || _b === void 0 ? void 0 : _b.search,
+                        }),
+                    lc: getLocale(),
+                    tz: getTimezone(),
+                    profileId: (_c = this.options) === null || _c === void 0 ? void 0 : _c.profileId,
+                }),
+            });
+            if (!response.ok) {
+                return null;
+            }
+            try {
+                const result = (await response.json());
+                const resolvedReplayId = typeof result.replayId === 'string' && result.replayId
+                    ? result.replayId
+                    : replayId;
+                const resolvedChunkIndex = typeof result.nextChunkIndex === 'number' &&
+                    Number.isFinite(result.nextChunkIndex) &&
+                    result.nextChunkIndex >= 0
+                    ? Math.floor(result.nextChunkIndex)
+                    : 0;
+                return {
+                    replayId: resolvedReplayId,
+                    nextChunkIndex: resolvedChunkIndex,
+                };
+            }
+            catch (_d) {
+                return {
+                    replayId,
+                    nextChunkIndex: 0,
+                };
+            }
+        }
+        catch (_e) {
+            return null;
+        }
+    }
+    async sendSessionReplayChunk(replayId, privacy, chunkIndex, events, useBeacon) {
+        const apiBase = this.getApiBase();
+        const url = `${apiBase}/log/session-replay/chunk`;
+        const payload = JSON.stringify({
+            pid: this.projectID,
+            replayId,
+            privacy,
+            chunkIndex,
+            events,
+        });
+        if (useBeacon && typeof navigator.sendBeacon === 'function') {
+            const sent = navigator.sendBeacon(url, new Blob([payload], { type: 'application/json' }));
+            if (sent)
+                return;
+        }
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                keepalive: useBeacon,
+                body: payload,
+            });
+        }
+        catch (_a) { }
+    }
     async sendRequest(path, body) {
         var _a;
         const host = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.apiURL) || DEFAULT_API_HOST;
@@ -670,6 +1199,12 @@ function trackErrors(options) {
     }
     return exports.LIB_INSTANCE.trackErrors(options);
 }
+function startSessionReplay(options) {
+    if (!exports.LIB_INSTANCE) {
+        return Promise.resolve(defaultSessionReplayActions);
+    }
+    return exports.LIB_INSTANCE.startSessionReplay(options);
+}
 /**
  * This function is used to manually track an error event.
  * It's useful if you want to track specific errors in your application.
@@ -704,17 +1239,16 @@ function pageview(options) {
 }
 /**
  * Fetches all feature flags for the project.
- * Results are cached for 5 minutes by default.
+ * Results are cached for 5 minutes by default and share a cache with experiments.
  *
- * @param options - Options for evaluating feature flags (visitorId, attributes).
+ * @param options - Options for evaluating feature flags (`profileId` only).
  * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
  * @returns A promise that resolves to a record of flag keys to boolean values.
  *
  * @example
  * ```typescript
  * const flags = await getFeatureFlags({
- *   visitorId: 'user-123',
- *   attributes: { cc: 'US', dv: 'desktop' }
+ *   profileId: 'user-123'
  * })
  *
  * if (flags['new-checkout']) {
@@ -731,13 +1265,13 @@ async function getFeatureFlags(options, forceRefresh) {
  * Gets the value of a single feature flag.
  *
  * @param key - The feature flag key.
- * @param options - Options for evaluating the feature flag (visitorId, attributes).
- * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @param options - Options for evaluating the feature flag (`profileId` only).
+ * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
  * @returns A promise that resolves to the boolean value of the flag.
  *
  * @example
  * ```typescript
- * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })
+ * const isEnabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
  *
  * if (isEnabled) {
  *   // Enable dark mode
@@ -750,8 +1284,8 @@ async function getFeatureFlag(key, options, defaultValue = false) {
     return exports.LIB_INSTANCE.getFeatureFlag(key, options, defaultValue);
 }
 /**
- * Clears the cached feature flags, forcing a fresh fetch on the next call.
- * Useful when you know the user's context has changed significantly.
+ * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
+ * Useful when you know the user's profile has changed.
  */
 function clearFeatureFlagsCache() {
     if (!exports.LIB_INSTANCE)
@@ -759,10 +1293,10 @@ function clearFeatureFlagsCache() {
     exports.LIB_INSTANCE.clearFeatureFlagsCache();
 }
 /**
- * Fetches all A/B test experiments for the project.
+ * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
  * Results are cached for 5 minutes by default (shared cache with feature flags).
  *
- * @param options - Options for evaluating experiments.
+ * @param options - Options for evaluating experiments (`profileId` only).
  * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
  * @returns A promise that resolves to a record of experiment IDs to variant keys.
  *
@@ -789,13 +1323,16 @@ async function getExperiments(options, forceRefresh) {
  * Gets the variant key for a specific A/B test experiment.
  *
  * @param experimentId - The experiment ID.
- * @param options - Options for evaluating the experiment.
- * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @param options - Options for evaluating the experiment (`profileId` only).
+ * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
  * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
  *
  * @example
  * ```typescript
- * const variant = await getExperiment('checkout-redesign-experiment-id')
+ * const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
+ *
+ * // Optional fallback variant:
+ * const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', undefined, 'control')
  *
  * if (variant === 'new-checkout') {
  *   // Show new checkout flow
@@ -889,6 +1426,7 @@ exports.getProfileId = getProfileId;
 exports.getSessionId = getSessionId;
 exports.init = init;
 exports.pageview = pageview;
+exports.startSessionReplay = startSessionReplay;
 exports.track = track;
 exports.trackError = trackError;
 exports.trackErrors = trackErrors;