@leanbase-giangnd/js 0.1.5 → 0.2.3

package/package.json

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

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

@@ -1,5 +1,103 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 import { window as win } from '../../utils'
-import { record as rrwebRecord } from '@rrweb/record'
+
+// 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.
@@ -12,9 +110,10 @@ const _target: any = (win as any) ?? (globalThis as any)
 
 _target.__PosthogExtensions__ = _target.__PosthogExtensions__ || {}
 
-// Expose rrweb.record under the same contract
+// 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: rrwebRecord,
+    record: rrwebRecordProxy,
 }
 
 // Provide initSessionRecording if not present — return a new LazyLoadedSessionRecording when called

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

@@ -1,5 +1,4 @@
 /* eslint-disable posthog-js/no-direct-function-check */
-import { record as rrwebRecord } from '@rrweb/record'
 import '../extension-shim'
 import { clampToRange, includes, isBoolean, isNullish, isNumber, isObject, isString, isUndefined } from '@posthog/core'
 import type { recordOptions, rrwebRecord as rrwebRecordType } from '../types/rrweb'
@@ -145,7 +144,43 @@ function getRRWebRecord(): rrwebRecordType | undefined {
         // ignore
     }
 
-    return rrwebRecord as unknown as rrwebRecordType
+    // If we've previously loaded rrweb via dynamic import, return the cached reference
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cached = (getRRWebRecord as any)._cachedRRWebRecord as rrwebRecordType | undefined
+    return cached as unknown as rrwebRecordType | undefined
+}
+
+async function loadRRWeb(): Promise<rrwebRecordType | null> {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ext = (globalThis as any).__PosthogExtensions__
+        if (ext && ext.rrweb && ext.rrweb.record) {
+            ;(getRRWebRecord as any)._cachedRRWebRecord = ext.rrweb.record as unknown as rrwebRecordType
+            return ext.rrweb.record as unknown as rrwebRecordType
+        }
+
+        // If already cached, return it
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const already = (getRRWebRecord as any)._cachedRRWebRecord as rrwebRecordType | undefined
+        if (already) {
+            return already
+        }
+
+        // Dynamic import - let the bundler (IIFE build) include rrweb in the bundle or allow lazy-load
+        // Note: we intentionally use a dynamic import so rrweb is not referenced at the module top-level
+        // which would cause IIFE builds to assume a global is present at script execution.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod: any = await import('@rrweb/record')
+        const rr = (mod && (mod.record ?? (mod.default && mod.default.record))) as rrwebRecordType
+        if (rr) {
+            ;(getRRWebRecord as any)._cachedRRWebRecord = rr
+            return rr
+        }
+    } catch (e) {
+        logger.error('could not dynamically load rrweb', e)
+    }
+
+    return null
 }
 
 export type compressedFullSnapshotEvent = {
@@ -681,7 +716,7 @@ export class LazyLoadedSessionRecording {
         return parsedConfig as SessionRecordingPersistedConfig
     }
 
-    start(startReason?: SessionStartReason) {
+    async start(startReason?: SessionStartReason) {
         const config = this._remoteConfig
         if (!config) {
             logger.info('remote config must be stored in persistence before recording can start')
@@ -722,7 +757,13 @@ export class LazyLoadedSessionRecording {
         })
 
         this._makeSamplingDecision(this.sessionId)
-        this._startRecorder()
+        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
+        }
 
         // calling addEventListener multiple times is safe and will not add duplicates
         addEventListener(window, 'beforeunload', this._onBeforeUnload)
@@ -1302,7 +1343,7 @@ export class LazyLoadedSessionRecording {
         }
     }
 
-    private _startRecorder() {
+    private async _startRecorder() {
         if (this._stopRrweb) {
             return
         }
@@ -1353,7 +1394,13 @@ export class LazyLoadedSessionRecording {
             sessionRecordingOptions.blockSelector = this._masking.blockSelector ?? undefined
         }
 
-        const rrwebRecord = getRRWebRecord()
+        // Ensure rrweb is loaded (either via global extension or dynamic import)
+        let rrwebRecord = getRRWebRecord()
+        if (!rrwebRecord) {
+            const loaded = await loadRRWeb()
+            rrwebRecord = loaded ?? undefined
+        }
+
         if (!rrwebRecord) {
             logger.error(
                 '_startRecorder was called but rrwebRecord is not available. This indicates something has gone wrong.'
@@ -1377,13 +1424,19 @@ export class LazyLoadedSessionRecording {
             })
 
         const activePlugins = this._gatherRRWebPlugins()
-        this._stopRrweb = rrwebRecord({
-            emit: (event) => {
-                this.onRRwebEmit(event)
-            },
-            plugins: activePlugins,
-            ...sessionRecordingOptions,
-        })
+        try {
+            this._stopRrweb = rrwebRecord({
+                emit: (event) => {
+                    this.onRRwebEmit(event)
+                },
+                plugins: activePlugins,
+                ...sessionRecordingOptions,
+            })
+        } catch (e) {
+            logger.error('failed to start rrweb recorder', e)
+            this._stopRrweb = undefined
+            return
+        }
 
         // We reset the last activity timestamp, resetting the idle timer
         this._lastActivityTimestamp = Date.now()

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

@@ -1,3 +1,4 @@
+/* eslint-disable posthog-js/no-direct-function-check */
 import { SESSION_RECORDING_IS_SAMPLED, SESSION_RECORDING_REMOTE_CONFIG } from '../../constants'
 import { Leanbase } from '../../leanbase'
 import { Properties, RemoteConfig, SessionRecordingPersistedConfig, SessionStartReason } from '../../types'
@@ -5,7 +6,7 @@ import { type eventWithTime } from './types/rrweb-types'
 
 import { isNullish, isUndefined } from '@posthog/core'
 import { logger } from '../../leanbase-logger'
-import { window } from '../../utils'
+import { assignableWindow, window } from '../../utils'
 import { LazyLoadedSessionRecording } from './external/lazy-loaded-session-recorder'
 import { DISABLED, LAZY_LOADING, SessionRecordingStatus, TriggerType } from './external/triggerMatching'
 
@@ -91,6 +92,19 @@ export class SessionRecording {
             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) => {
+                if (err) {
+                    return log.error('could not load recorder', err)
+                }
+                this._onScriptLoaded(startReason)
+            })
+            return
+        }
+
         this._onScriptLoaded(startReason)
     }
 
@@ -188,14 +202,57 @@ export class SessionRecording {
         }
     }
 
+    private get _scriptName() {
+        const remoteConfig: SessionRecordingPersistedConfig | undefined = this._instance?.persistence?.get_property(
+            SESSION_RECORDING_REMOTE_CONFIG
+        )
+        return (remoteConfig?.scriptConfig?.script as any) || 'lazy-recorder'
+    }
+
     private _onScriptLoaded(startReason?: SessionStartReason) {
+        // If extensions provide an init function, use it. Otherwise, fall back to the local LazyLoadedSessionRecording
+        if (assignableWindow.__PosthogExtensions__?.initSessionRecording) {
+            if (!this._lazyLoadedSessionRecording) {
+                const maybeRecording = assignableWindow.__PosthogExtensions__?.initSessionRecording(this._instance)
+                if (maybeRecording && typeof (maybeRecording as any).start === 'function') {
+                    this._lazyLoadedSessionRecording = maybeRecording
+                    ;(this._lazyLoadedSessionRecording as any)._forceAllowLocalhostNetworkCapture =
+                        this._forceAllowLocalhostNetworkCapture
+                } else {
+                    log.warn(
+                        'initSessionRecording was present but did not return a recorder instance; falling back to local recorder'
+                    )
+                }
+            }
+
+            if (this._lazyLoadedSessionRecording) {
+                try {
+                    const maybePromise: any = this._lazyLoadedSessionRecording.start(startReason)
+                    if (maybePromise && typeof maybePromise.catch === 'function') {
+                        maybePromise.catch((e: any) => logger.error('error starting session recording', e))
+                    }
+                } catch (e: any) {
+                    logger.error('error starting session recording', e)
+                }
+                return
+            }
+        }
+
         if (!this._lazyLoadedSessionRecording) {
             this._lazyLoadedSessionRecording = new LazyLoadedSessionRecording(this._instance)
             ;(this._lazyLoadedSessionRecording as any)._forceAllowLocalhostNetworkCapture =
                 this._forceAllowLocalhostNetworkCapture
         }
 
-        this._lazyLoadedSessionRecording.start(startReason)
+        // start may perform a dynamic import; handle both sync and Promise returns
+        try {
+            const maybePromise: any = this._lazyLoadedSessionRecording!.start(startReason)
+            if (maybePromise && typeof maybePromise.catch === 'function') {
+                maybePromise.catch((e: any) => logger.error('error starting session recording', e))
+            }
+        } catch (e: any) {
+            logger.error('error starting session recording', e)
+        }
     }
 
     /**

package/src/leanbase.ts

@@ -93,6 +93,10 @@ export class Leanbase extends PostHogCore {
     consent!: ConsentManager
     sessionRecording?: SessionRecording
     isRemoteConfigLoaded?: boolean
+    private _remoteConfigLoadAttempted: boolean = false
+    private _remoteConfigResolved: boolean = false
+    private _featureFlagsResolved: boolean = false
+    private _maybeStartedSessionRecording: boolean = false
     personProcessingSetOncePropertiesSent = false
     isLoaded: boolean = false
     initialPageviewCaptured: boolean
@@ -130,11 +134,21 @@ export class Leanbase extends PostHogCore {
 
         if (this.sessionManager && this.config.cookieless_mode !== 'always') {
             this.sessionRecording = new SessionRecording(this)
-            this.sessionRecording.startIfEnabledOrStop()
         }
 
+        // Start session recording only once flags + remote config have been resolved.
+        // This matches the PostHog browser SDK where replay activation is driven by remote config and flags.
         if (this.config.preloadFeatureFlags !== false) {
-            this.reloadFeatureFlags()
+            this.reloadFeatureFlags({
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                cb: (_err) => {
+                    this._featureFlagsResolved = true
+                    this._maybeStartSessionRecording()
+                },
+            })
+        } else {
+            // If feature flags preload is explicitly disabled, treat this requirement as satisfied.
+            this._featureFlagsResolved = true
         }
 
         this.config.loaded?.(this)
@@ -146,9 +160,25 @@ export class Leanbase extends PostHogCore {
             }, 1)
         }
 
-        addEventListener(document, 'DOMContentLoaded', () => {
-            this.loadRemoteConfig()
-        })
+        const triggerRemoteConfigLoad = (reason: 'immediate' | 'dom' | 'no-document') => {
+            logger.info(`remote config load triggered via ${reason}`)
+            void this.loadRemoteConfig()
+        }
+
+        if (document) {
+            if (document.readyState === 'loading') {
+                logger.info('remote config load deferred until DOMContentLoaded')
+                const onDomReady = () => {
+                    document?.removeEventListener('DOMContentLoaded', onDomReady)
+                    triggerRemoteConfigLoad('dom')
+                }
+                addEventListener(document, 'DOMContentLoaded', onDomReady, { once: true } as any)
+            } else {
+                triggerRemoteConfigLoad('immediate')
+            }
+        } else {
+            triggerRemoteConfigLoad('no-document')
+        }
         addEventListener(window, 'onpagehide' in self ? 'pagehide' : 'unload', this.capturePageLeave.bind(this), {
             passive: false,
         })
@@ -191,11 +221,20 @@ export class Leanbase extends PostHogCore {
     }
 
     async loadRemoteConfig() {
-        if (!this.isRemoteConfigLoaded) {
+        if (this._remoteConfigLoadAttempted) {
+            return
+        }
+        this._remoteConfigLoadAttempted = true
+
+        try {
             const remoteConfig = await this.reloadRemoteConfigAsync()
             if (remoteConfig) {
                 this.onRemoteConfig(remoteConfig as RemoteConfig)
             }
+        } finally {
+            // Regardless of success/failure, we consider remote config "resolved" so replay isn't blocked forever.
+            this._remoteConfigResolved = true
+            this._maybeStartSessionRecording()
         }
     }
 
@@ -210,6 +249,29 @@ export class Leanbase extends PostHogCore {
         this.isRemoteConfigLoaded = true
         this.replayAutocapture?.onRemoteConfig(config)
         this.sessionRecording?.onRemoteConfig(config)
+
+        // Remote config has been applied; allow replay start if flags are also ready.
+        this._remoteConfigResolved = true
+        this._maybeStartSessionRecording()
+    }
+
+    private _maybeStartSessionRecording(): void {
+        if (this._maybeStartedSessionRecording) {
+            return
+        }
+        if (!this.sessionRecording) {
+            return
+        }
+        if (!this._featureFlagsResolved || !this._remoteConfigResolved) {
+            return
+        }
+
+        this._maybeStartedSessionRecording = true
+        try {
+            this.sessionRecording.startIfEnabledOrStop()
+        } catch (e) {
+            logger.error('Failed to start session recording', e)
+        }
     }
 
     fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse> {

package/src/utils/index.ts

@@ -22,6 +22,9 @@ export const AbortController = global?.AbortController
 export const userAgent = navigator?.userAgent
 export { win as window }
 
+// assignableWindow mirrors browser package's assignableWindow for extension loading shims
+export const assignableWindow: (Window & typeof globalThis) | any = win ?? ({} as any)
+
 export function eachArray<E = any>(
     obj: E[] | null | undefined,
     iterator: (value: E, key: number) => void | Breaker,

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.1.5'
+export const version = '0.2.3'