@leanbase-giangnd/js 0.2.4 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@leanbase-giangnd/js",
-    "version": "0.2.4",
+    "version": "0.3.1",
     "description": "Leanbase browser SDK - event tracking, autocapture, and session replay",
     "repository": {
         "type": "git",

package/src/extensions/replay/extension-shim.ts

@@ -1,122 +1,13 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { window as win } from '../../utils'
-
-// We avoid importing '@rrweb/record' at module load time to prevent IIFE builds
-// from requiring a top-level global. Instead, expose a lazy proxy that will
-// dynamically import the module the first time it's used.
-
-let _cachedRRWeb: any | null = null
-
-async function _loadRRWebModule(): Promise<any> {
-    if (_cachedRRWeb) return _cachedRRWeb
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const mod: any = await import('@rrweb/record')
-        _cachedRRWeb = mod
-        return _cachedRRWeb
-    } catch (e) {
-        return null
-    }
-}
-
-// queue for method calls before rrweb loads
-const _queuedCalls: Array<() => void> = []
-
-// Create a proxy function that delegates to the real rrweb.record when called
-const rrwebRecordProxy: any = function (...args: any[]) {
-    let realStop: (() => void) | undefined
-    let calledReal = false
-
-    // Start loading asynchronously and call the real record when available
-    void (async () => {
-        const mod = await _loadRRWebModule()
-        const real = mod && (mod.record ?? mod.default?.record)
-        if (real) {
-            try {
-                calledReal = true
-                realStop = real(...args)
-                // flush any queued calls that were waiting for rrweb
-                while (_queuedCalls.length) {
-                    try {
-                        const fn = _queuedCalls.shift()!
-                        fn()
-                    } catch (e) {
-                        // ignore
-                    }
-                }
-            } catch (e) {
-                // ignore
-            }
-        }
-    })()
-
-    // return a stop function that will call the real stop when available
-    return () => {
-        if (realStop) {
-            try {
-                realStop()
-            } catch (e) {
-                // ignore
-            }
-        } else if (!calledReal) {
-            // If rrweb hasn't been initialised yet, queue a stop request that will
-            // call the real stop once available.
-            _queuedCalls.push(() => {
-                try {
-                    realStop?.()
-                } catch (e) {
-                    // ignore
-                }
-            })
-        }
-    }
-}
-
-// methods that can be called on the rrweb.record object - queue until real module is available
-rrwebRecordProxy.addCustomEvent = function (tag?: string, payload?: any) {
-    const call = () => {
-        try {
-            const real = _cachedRRWeb && (_cachedRRWeb.record ?? _cachedRRWeb.default?.record)
-            real?.addCustomEvent?.(tag, payload)
-        } catch (e) {
-            // ignore
-        }
-    }
-    if (_cachedRRWeb) call()
-    else _queuedCalls.push(call)
-}
-
-rrwebRecordProxy.takeFullSnapshot = function () {
-    const call = () => {
-        try {
-            const real = _cachedRRWeb && (_cachedRRWeb.record ?? _cachedRRWeb.default?.record)
-            real?.takeFullSnapshot?.()
-        } catch (e) {
-            // ignore
-        }
-    }
-    if (_cachedRRWeb) call()
-    else _queuedCalls.push(call)
-}
-// Delay importing heavy modules to avoid circular dependencies at build time.
-// They will be required lazily when used at runtime.
-// We avoid requiring the lazy-loaded recorder here to prevent circular dependencies during bundling.
-// Instead, `LazyLoadedSessionRecording` will register a factory on the global under
-// `__PosthogExtensions__._initSessionRecordingFactory` when it loads.
 type InitSessionRecordingFactory = (instance: any) => any
 
-// Use a safe global target (prefer `win`, fallback to globalThis)
 const _target: any = (win as any) ?? (globalThis as any)
 
 _target.__PosthogExtensions__ = _target.__PosthogExtensions__ || {}
 
-// Expose rrweb.record under the same contract. We provide a lazy proxy so
-// builds that execute this file don't require rrweb at module evaluation time.
-_target.__PosthogExtensions__.rrweb = _target.__PosthogExtensions__.rrweb || {
-    record: rrwebRecordProxy,
-}
+_target.__PosthogExtensions__.rrweb = _target.__PosthogExtensions__.rrweb || {}
 
-// Provide initSessionRecording if not present — return a new LazyLoadedSessionRecording when called
 _target.__PosthogExtensions__.initSessionRecording =
     _target.__PosthogExtensions__.initSessionRecording ||
     ((instance: any) => {
@@ -125,20 +16,16 @@ _target.__PosthogExtensions__.initSessionRecording =
         if (factory) {
             return factory(instance)
         }
-        // If no factory is registered yet, return undefined — callers should handle lazy-loading.
         return undefined
     })
 
-// Provide a no-op loadExternalDependency that calls the callback immediately (since rrweb is bundled)
 _target.__PosthogExtensions__.loadExternalDependency =
     _target.__PosthogExtensions__.loadExternalDependency ||
     ((instance: any, scriptName: string, cb?: (err?: any) => void) => {
         if (cb) cb(undefined)
     })
 
-// Provide rrwebPlugins object with network plugin factory if not present
 _target.__PosthogExtensions__.rrwebPlugins = _target.__PosthogExtensions__.rrwebPlugins || {}
-// Default to undefined; the lazy-loaded recorder will register the real factory when it initializes.
 _target.__PosthogExtensions__.rrwebPlugins.getRecordNetworkPlugin =
     _target.__PosthogExtensions__.rrwebPlugins.getRecordNetworkPlugin || (() => undefined)
 

package/src/extensions/replay/external/lazy-loaded-session-recorder.ts

@@ -318,7 +318,12 @@ export class LazyLoadedSessionRecording {
      * Util to help developers working on this feature manually override
      */
     private _forceAllowLocalhostNetworkCapture = false
+    // "Started" is only true once we have a valid rrweb stop handler AND we have marked recording enabled.
+    // If rrweb fails to initialize, we permanently disable replay for this page load.
+    private _recording: { stop: listenerHandler } | undefined
     private _stopRrweb: listenerHandler | undefined = undefined
+    private _permanentlyDisabled: boolean = false
+    private _loggedPermanentlyDisabled: boolean = false
     private _lastActivityTimestamp: number = Date.now()
     /**
      * if pageview capture is disabled,
@@ -357,6 +362,25 @@ export class LazyLoadedSessionRecording {
 
     private _removeEventTriggerCaptureHook: (() => void) | undefined = undefined
 
+    private _disablePermanently(reason: string, error?: unknown): void {
+        this._permanentlyDisabled = true
+        this._isFullyReady = false
+        this._mutationThrottler?.stop()
+        this._mutationThrottler = undefined
+        this._queuedRRWebEvents = []
+        this._recording = undefined
+        this._stopRrweb = undefined
+
+        if (!this._loggedPermanentlyDisabled) {
+            this._loggedPermanentlyDisabled = true
+            if (error) {
+                logger.error(`replay disabled: ${reason}`, error)
+            } else {
+                logger.error(`replay disabled: ${reason}`)
+            }
+        }
+    }
+
     private get _sessionManager() {
         if (!this._instance.sessionManager) {
             throw new Error(LOGGER_PREFIX + ' must be started with a valid sessionManager.')
@@ -579,6 +603,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _tryAddCustomEvent(tag: string, payload: any): boolean {
+        if (!this.isStarted || !this._recording) {
+            return false
+        }
         const rrwebRecord = getRRWebRecord()
         if (!rrwebRecord || typeof (rrwebRecord as any).addCustomEvent !== 'function') {
             return false
@@ -609,6 +636,10 @@ export class LazyLoadedSessionRecording {
     }
 
     private _processQueuedEvents() {
+        if (!this.isStarted || !this._recording) {
+            this._queuedRRWebEvents = []
+            return
+        }
         if (this._queuedRRWebEvents.length) {
             // if rrweb isn't ready to accept events earlier, then we queued them up.
             // now that `emit` has been called rrweb should be ready to accept them.
@@ -631,6 +662,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _tryTakeFullSnapshot(): boolean {
+        if (!this.isStarted || !this._recording) {
+            return false
+        }
         const rrwebRecord = getRRWebRecord()
         if (!rrwebRecord || typeof (rrwebRecord as any).takeFullSnapshot !== 'function') {
             return false
@@ -651,6 +685,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _scheduleFullSnapshot(): void {
+        if (!this.isStarted || !this._recording) {
+            return
+        }
         if (this._fullSnapshotTimer) {
             clearInterval(this._fullSnapshotTimer)
         }
@@ -670,6 +707,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _pauseRecording() {
+        if (!this.isStarted || !this._recording) {
+            return
+        }
         // we check _urlBlocked not status, since more than one thing can affect status
         if (this._urlTriggerMatching.urlBlocked) {
             return
@@ -689,6 +729,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _resumeRecording() {
+        if (!this.isStarted || !this._recording) {
+            return
+        }
         // we check _urlBlocked not status, since more than one thing can affect status
         if (!this._urlTriggerMatching.urlBlocked) {
             return
@@ -704,6 +747,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _activateTrigger(triggerType: TriggerType) {
+        if (!this.isStarted || !this._recording || !this._isFullyReady) {
+            return
+        }
         if (this._triggerMatching.triggerStatus(this.sessionId) === TRIGGER_PENDING) {
             // status is stored separately for URL and event triggers
             this._instance?.persistence?.register({
@@ -718,7 +764,7 @@ export class LazyLoadedSessionRecording {
     }
 
     get isStarted(): boolean {
-        return !!this._stopRrweb
+        return !!this._recording?.stop
     }
 
     get _remoteConfig(): SessionRecordingPersistedConfig | undefined {
@@ -731,6 +777,9 @@ export class LazyLoadedSessionRecording {
     }
 
     async start(startReason?: SessionStartReason) {
+        if (this._permanentlyDisabled) {
+            return
+        }
         this._isFullyReady = false
         const config = this._remoteConfig
         if (!config) {
@@ -761,9 +810,17 @@ export class LazyLoadedSessionRecording {
         this._urlTriggerMatching.onConfig(config)
 
         this._eventTriggerMatching.onConfig(config)
-        this._removeEventTriggerCaptureHook?.()
-        this._addEventTriggerListener()
 
+        // Start rrweb first; only once we have a valid recorder do we install any listeners/timers.
+        await this._startRecorder()
+
+        // If rrweb failed to load/start, do not proceed further.
+        // This prevents installing listeners that assume rrweb is active.
+        if (!this.isStarted) {
+            return
+        }
+
+        // Now that rrweb has started, we can safely install replay side-effects.
         this._linkedFlagMatching.onConfig(config, (flag, variant) => {
             this._reportStarted('linked_flag_matched', {
                 flag,
@@ -772,13 +829,8 @@ export class LazyLoadedSessionRecording {
         })
 
         this._makeSamplingDecision(this.sessionId)
-        await this._startRecorder()
-
-        // If rrweb failed to load/start, do not proceed further.
-        // This prevents installing listeners that assume rrweb is active.
-        if (!this.isStarted) {
-            return
-        }
+        this._removeEventTriggerCaptureHook?.()
+        this._addEventTriggerListener()
 
         // Only start processing rrweb emits once the ingestion endpoint is available.
         // If it isn't available, we must degrade to a no-op (never crash the host app).
@@ -886,9 +938,9 @@ export class LazyLoadedSessionRecording {
         // Clear any queued rrweb events to prevent memory leaks from closures
         this._queuedRRWebEvents = []
 
-        this._stopRrweb?.()
+        this._recording?.stop?.()
+        this._recording = undefined
         this._stopRrweb = undefined
-
         this._isFullyReady = false
 
         logger.info('stopped')
@@ -911,8 +963,13 @@ export class LazyLoadedSessionRecording {
     }
 
     onRRwebEmit(rawEvent: eventWithTime) {
+        // First-line invariant gate: drop everything unless replay is truly started.
+        if (!this.isStarted || !this._recording) {
+            return
+        }
+
         // Never process rrweb emits until we're fully ready.
-        if (!this._isFullyReady || !this.isStarted) {
+        if (!this._isFullyReady) {
             return
         }
 
@@ -1046,6 +1103,9 @@ export class LazyLoadedSessionRecording {
     }
 
     public overrideLinkedFlag() {
+        if (!this.isStarted || !this._recording || !this._isFullyReady) {
+            return
+        }
         this._linkedFlagMatching.linkedFlagSeen = true
         this._tryTakeFullSnapshot()
         this._reportStarted('linked_flag_overridden')
@@ -1058,6 +1118,9 @@ export class LazyLoadedSessionRecording {
      * instead call `posthog.startSessionRecording({sampling: true})`
      * */
     public overrideSampling() {
+        if (!this.isStarted || !this._recording || !this._isFullyReady) {
+            return
+        }
         this._instance.persistence?.register({
             // short-circuits the `makeSamplingDecision` function in the session recording module
             [SESSION_RECORDING_IS_SAMPLED]: this.sessionId,
@@ -1073,6 +1136,9 @@ export class LazyLoadedSessionRecording {
      * instead call `posthog.startSessionRecording({trigger: 'url' | 'event'})`
      * */
     public overrideTrigger(triggerType: TriggerType) {
+        if (!this.isStarted || !this._recording || !this._isFullyReady) {
+            return
+        }
         this._activateTrigger(triggerType)
     }
 
@@ -1243,6 +1309,9 @@ export class LazyLoadedSessionRecording {
     }
 
     private _reportStarted(startReason: SessionStartReason, tagPayload?: Record<string, any>) {
+        if (!this.isStarted || !this._recording) {
+            return
+        }
         this._instance.registerForSession({
             $session_recording_start_reason: startReason,
         })
@@ -1416,7 +1485,7 @@ export class LazyLoadedSessionRecording {
     }
 
     private async _startRecorder() {
-        if (this._stopRrweb) {
+        if (this._permanentlyDisabled || this._recording) {
             return
         }
 
@@ -1474,46 +1543,56 @@ export class LazyLoadedSessionRecording {
         }
 
         if (!rrwebRecord) {
-            logger.error(
-                '_startRecorder was called but rrwebRecord is not available. This indicates something has gone wrong.'
-            )
+            this._disablePermanently('rrweb record function unavailable')
             return
         }
 
-        this._mutationThrottler =
-            this._mutationThrottler ??
-            new MutationThrottler(rrwebRecord, {
-                refillRate: this._instance.config.session_recording?.__mutationThrottlerRefillRate,
-                bucketSize: this._instance.config.session_recording?.__mutationThrottlerBucketSize,
-                onBlockedNode: (id, node) => {
-                    const message = `Too many mutations on node '${id}'. Rate limiting. This could be due to SVG animations or something similar`
-                    logger.info(message, {
-                        node: node,
-                    })
-
-                    this.log(LOGGER_PREFIX + ' ' + message, 'warn')
-                },
-            })
-
         const activePlugins = this._gatherRRWebPlugins()
+
+        let stopHandler: listenerHandler | undefined
         try {
-            this._stopRrweb = rrwebRecord({
+            stopHandler = rrwebRecord({
                 emit: (event) => {
                     try {
                         this.onRRwebEmit(event)
                     } catch (e) {
+                        // never throw from rrweb emit handler
                         logger.error('error in rrweb emit handler', e)
                     }
                 },
                 plugins: activePlugins,
                 ...sessionRecordingOptions,
-            })
+            }) as unknown as listenerHandler
         } catch (e) {
-            logger.error('failed to start rrweb recorder', e)
-            this._stopRrweb = undefined
+            this._disablePermanently('rrweb recorder threw during initialization', e)
+            return
+        }
+
+        if (typeof stopHandler !== 'function') {
+            this._disablePermanently('rrweb recorder returned an invalid stop handler')
             return
         }
 
+        // Mark replay started only after rrweb has successfully returned a valid stop handler.
+        this._recording = { stop: stopHandler }
+        this._stopRrweb = stopHandler
+
+        // Only create mutation throttler once replay is truly started.
+        this._mutationThrottler =
+            this._mutationThrottler ??
+            new MutationThrottler(rrwebRecord, {
+                refillRate: this._instance.config.session_recording?.__mutationThrottlerRefillRate,
+                bucketSize: this._instance.config.session_recording?.__mutationThrottlerBucketSize,
+                onBlockedNode: (id, node) => {
+                    const message = `Too many mutations on node '${id}'. Rate limiting. This could be due to SVG animations or something similar`
+                    logger.info(message, {
+                        node: node,
+                    })
+
+                    this.log(LOGGER_PREFIX + ' ' + message, 'warn')
+                },
+            })
+
         // We reset the last activity timestamp, resetting the idle timer
         this._lastActivityTimestamp = Date.now()
         // stay unknown if we're not sure if we're idle or not

package/src/extensions/replay/external/mutation-throttler.ts

@@ -16,11 +16,8 @@ export class MutationThrottler {
             onBlockedNode?: (id: number, node: Node | null) => void
         } = {}
     ) {
-        const configuredBucketSize = this._options.bucketSize ?? 100
-        const effectiveBucketSize = Math.max(configuredBucketSize - 1, 1)
-
         this._rateLimiter = new BucketedRateLimiter({
-            bucketSize: effectiveBucketSize,
+            bucketSize: this._options.bucketSize ?? 100,
             refillRate: this._options.refillRate ?? 10,
             refillInterval: 1000, // one second
             _onBucketRateLimited: this._onNodeRateLimited,

package/src/extensions/replay/session-recording.ts

@@ -21,7 +21,6 @@ export class SessionRecording {
     _forceAllowLocalhostNetworkCapture: boolean = false
 
     private _receivedFlags: boolean = false
-    private _serverRecordingEnabled: boolean = false
 
     private _persistFlagsOnSessionListener: (() => void) | undefined = undefined
     private _lazyLoadedSessionRecording: LazyLoadedSessionRecording | undefined
@@ -30,10 +29,6 @@ export class SessionRecording {
         return !!this._lazyLoadedSessionRecording?.isStarted
     }
 
-    /**
-     * defaults to buffering mode until a flags response is received
-     * once a flags response is received status can be disabled, active or sampled
-     */
     get status(): SessionRecordingStatus {
         if (this._lazyLoadedSessionRecording) {
             return this._lazyLoadedSessionRecording.status
@@ -72,28 +67,16 @@ export class SessionRecording {
         const canRunReplay = !isUndefined(Object.assign) && !isUndefined(Array.from)
         if (this._isRecordingEnabled && canRunReplay) {
             this._lazyLoadAndStart(startReason)
-            log.info('starting')
         } else {
             this.stopRecording()
         }
     }
 
-    /**
-     * session recording waits until it receives remote config before loading the script
-     * this is to ensure we can control the script name remotely
-     * and because we wait until we have local and remote config to determine if we should start at all
-     * if start is called and there is no remote config then we wait until there is
-     */
     private _lazyLoadAndStart(startReason?: SessionStartReason) {
-        // by checking `_isRecordingEnabled` here we know that
-        // we have stored remote config and client config to read
-        // replay waits for both local and remote config before starting
         if (!this._isRecordingEnabled) {
             return
         }
 
-        // If extensions provide a loader, use it. Otherwise fallback to the local _onScriptLoaded which
-        // will create the local LazyLoadedSessionRecording (so tests that mock it work correctly).
         const loader = assignableWindow.__PosthogExtensions__?.loadExternalDependency
         if (typeof loader === 'function') {
             loader(this._instance, this._scriptName as any, (err: any) => {
@@ -162,18 +145,11 @@ export class SessionRecording {
 
             persistResponse()
 
-            // in case we see multiple flags responses, we should only use the response from the most recent one
             this._persistFlagsOnSessionListener?.()
-            // we 100% know there is a session manager by this point
             this._persistFlagsOnSessionListener = this._instance.sessionManager?.onSessionId(persistResponse)
         }
     }
 
-    private _clearRemoteConfig() {
-        this._instance.persistence?.unregister(SESSION_RECORDING_REMOTE_CONFIG)
-        this._resetSampling()
-    }
-
     onRemoteConfig(response: RemoteConfig) {
         if (!('sessionRecording' in response)) {
             // if sessionRecording is not in the response, we do nothing
@@ -183,13 +159,9 @@ export class SessionRecording {
         this._receivedFlags = true
 
         if (response.sessionRecording === false) {
-            this._serverRecordingEnabled = false
-            this._clearRemoteConfig()
-            this.stopRecording()
             return
         }
 
-        this._serverRecordingEnabled = true
         this._persistRemoteConfig(response)
         this.startIfEnabledOrStop()
     }
@@ -264,44 +236,21 @@ export class SessionRecording {
         this._lazyLoadedSessionRecording?.onRRwebEmit?.(rawEvent)
     }
 
-    /**
-     * this ignores the linked flag config and (if other conditions are met) causes capture to start
-     *
-     * It is not usual to call this directly,
-     * instead call `posthog.startSessionRecording({linked_flag: true})`
-     * */
     public overrideLinkedFlag() {
         // TODO what if this gets called before lazy loading is done
         this._lazyLoadedSessionRecording?.overrideLinkedFlag()
     }
 
-    /**
-     * this ignores the sampling config and (if other conditions are met) causes capture to start
-     *
-     * It is not usual to call this directly,
-     * instead call `posthog.startSessionRecording({sampling: true})`
-     * */
     public overrideSampling() {
         // TODO what if this gets called before lazy loading is done
         this._lazyLoadedSessionRecording?.overrideSampling()
     }
 
-    /**
-     * this ignores the URL/Event trigger config and (if other conditions are met) causes capture to start
-     *
-     * It is not usual to call this directly,
-     * instead call `posthog.startSessionRecording({trigger: 'url' | 'event'})`
-     * */
     public overrideTrigger(triggerType: TriggerType) {
         // TODO what if this gets called before lazy loading is done
         this._lazyLoadedSessionRecording?.overrideTrigger(triggerType)
     }
 
-    /*
-     * whenever we capture an event, we add these properties to the event
-     * these are used to debug issues with the session recording
-     * when looking at the event feed for a session
-     */
     get sdkDebugProperties(): Properties {
         return (
             this._lazyLoadedSessionRecording?.sdkDebugProperties || {
@@ -310,14 +259,6 @@ export class SessionRecording {
         )
     }
 
-    /**
-     * This adds a custom event to the session recording
-     *
-     * It is not intended for arbitrary public use - playback only displays known custom events
-     * And is exposed on the public interface only so that other parts of the SDK are able to use it
-     *
-     * if you are calling this from client code, you're probably looking for `posthog.capture('$custom_event', {...})`
-     */
     tryAddCustomEvent(tag: string, payload: any): boolean {
         return !!this._lazyLoadedSessionRecording?.tryAddCustomEvent(tag, payload)
     }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.2.4'
+export const version = '0.3.1'