@leanbase-giangnd/js 0.2.2 → 0.2.4

package/package.json

@@ -1,47 +1,48 @@
 {
-  "name": "@leanbase-giangnd/js",
-  "version": "0.2.2",
-  "description": "Leanbase browser SDK - event tracking, autocapture, and session replay",
-  "repository": {
-    "type": "git",
-    "directory": "packages/leanbase"
-  },
-  "author": "leanbase",
-  "license": "Copyrighted by Leanflag Limited",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "unpkg": "dist/leanbase.iife.js",
-  "jsdelivr": "dist/leanbase.iife.js",
-  "files": [
-    "dist",
-    "src",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@rrweb/record": "2.0.0-alpha.17",
-    "fflate": "^0.4.8",
-    "@posthog/core": "1.3.1"
-  },
-  "devDependencies": {
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "rollup": "^4.44.1",
-    "rimraf": "^6.0.1",
-    "@posthog-tooling/tsconfig-base": "1.0.0",
-    "@posthog-tooling/rollup-utils": "1.0.0"
-  },
-  "scripts": {
-    "clean": "rimraf dist coverage",
-    "test:unit": "jest -c jest.config.js",
-    "lint": "eslint src test",
-    "lint:fix": "eslint src test --fix",
-    "prebuild": "node -p \"'export const version = \\'' + require('./package.json').version + '\\''\" > src/version.ts",
-    "build": "rollup -c",
-    "dev": "rollup -c -w",
-    "package": "mkdir -p ../../target && pnpm pack --pack-destination ../../target"
-  }
-}
+    "name": "@leanbase-giangnd/js",
+    "version": "0.2.4",
+    "description": "Leanbase browser SDK - event tracking, autocapture, and session replay",
+    "repository": {
+        "type": "git",
+        "directory": "packages/leanbase"
+    },
+    "author": "leanbase",
+    "license": "Copyrighted by Leanflag Limited",
+    "main": "dist/index.cjs",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "unpkg": "dist/leanbase.iife.js",
+    "jsdelivr": "dist/leanbase.iife.js",
+    "scripts": {
+        "clean": "rimraf dist coverage",
+        "test:unit": "jest -c jest.config.js",
+        "lint": "eslint src test",
+        "lint:fix": "eslint src test --fix",
+        "prebuild": "node -p \"'export const version = \\'' + require('./package.json').version + '\\''\" > src/version.ts",
+        "build": "rollup -c",
+        "dev": "rollup -c -w",
+        "prepublishOnly": "pnpm lint && pnpm test:unit && pnpm build",
+        "package": "mkdir -p ../../target && pnpm pack --pack-destination ../../target"
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@posthog/core": "workspace:*",
+        "@rrweb/record": "2.0.0-alpha.17",
+        "fflate": "^0.4.8"
+    },
+    "devDependencies": {
+        "@posthog-tooling/tsconfig-base": "workspace:*",
+        "@posthog-tooling/rollup-utils": "workspace:*",
+        "jest": "catalog:",
+        "jest-environment-jsdom": "catalog:",
+        "rollup": "catalog:",
+        "rimraf": "^6.0.1"
+    }
+}

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

@@ -331,6 +331,10 @@ export class LazyLoadedSessionRecording {
     private _queuedRRWebEvents: QueuedRRWebEvent[] = []
     private _isIdle: boolean | 'unknown' = 'unknown'
 
+    // Replay should not process rrweb emits until all critical dependencies are ready.
+    private _isFullyReady: boolean = false
+    private _loggedMissingEndpointFor: boolean = false
+
     private _linkedFlagMatching: LinkedFlagMatching
     private _urlTriggerMatching: URLTriggerMatching
     private _eventTriggerMatching: EventTriggerMatching
@@ -575,7 +579,12 @@ export class LazyLoadedSessionRecording {
     }
 
     private _tryAddCustomEvent(tag: string, payload: any): boolean {
-        return this._tryRRWebMethod(newQueuedEvent(() => getRRWebRecord()!.addCustomEvent(tag, payload)))
+        const rrwebRecord = getRRWebRecord()
+        if (!rrwebRecord || typeof (rrwebRecord as any).addCustomEvent !== 'function') {
+            return false
+        }
+
+        return this._tryRRWebMethod(newQueuedEvent(() => (rrwebRecord as any).addCustomEvent(tag, payload)))
     }
 
     private _pageViewFallBack() {
@@ -622,7 +631,12 @@ export class LazyLoadedSessionRecording {
     }
 
     private _tryTakeFullSnapshot(): boolean {
-        return this._tryRRWebMethod(newQueuedEvent(() => getRRWebRecord()!.takeFullSnapshot()))
+        const rrwebRecord = getRRWebRecord()
+        if (!rrwebRecord || typeof (rrwebRecord as any).takeFullSnapshot !== 'function') {
+            return false
+        }
+
+        return this._tryRRWebMethod(newQueuedEvent(() => (rrwebRecord as any).takeFullSnapshot()))
     }
 
     private get _fullSnapshotIntervalMillis(): number {
@@ -717,6 +731,7 @@ export class LazyLoadedSessionRecording {
     }
 
     async start(startReason?: SessionStartReason) {
+        this._isFullyReady = false
         const config = this._remoteConfig
         if (!config) {
             logger.info('remote config must be stored in persistence before recording can start')
@@ -759,6 +774,16 @@ 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
+        }
+
+        // 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).
+        this._isFullyReady = this._canCaptureSnapshots()
+
         // calling addEventListener multiple times is safe and will not add duplicates
         addEventListener(window, 'beforeunload', this._onBeforeUnload)
         addEventListener(window, 'offline', this._onOffline)
@@ -864,101 +889,130 @@ export class LazyLoadedSessionRecording {
         this._stopRrweb?.()
         this._stopRrweb = undefined
 
+        this._isFullyReady = false
+
         logger.info('stopped')
     }
 
-    onRRwebEmit(rawEvent: eventWithTime) {
-        this._processQueuedEvents()
+    private _snapshotIngestionUrl(): string | null {
+        const endpointFor = (this._instance as any)?.requestRouter?.endpointFor
+        if (typeof endpointFor !== 'function') {
+            return null
+        }
+        try {
+            return endpointFor('api', this._endpoint)
+        } catch {
+            return null
+        }
+    }
+
+    private _canCaptureSnapshots(): boolean {
+        return !!this._snapshotIngestionUrl()
+    }
 
-        if (!rawEvent || !isObject(rawEvent)) {
+    onRRwebEmit(rawEvent: eventWithTime) {
+        // Never process rrweb emits until we're fully ready.
+        if (!this._isFullyReady || !this.isStarted) {
             return
         }
 
-        if (rawEvent.type === EventType.Meta) {
-            const href = this._maskUrl(rawEvent.data.href)
-            this._lastHref = href
-            if (!href) {
+        try {
+            this._processQueuedEvents()
+
+            if (!rawEvent || !isObject(rawEvent)) {
                 return
             }
-            rawEvent.data.href = href
-        } else {
-            this._pageViewFallBack()
-        }
 
-        // Check if the URL matches any trigger patterns
-        this._urlTriggerMatching.checkUrlTriggerConditions(
-            () => this._pauseRecording(),
-            () => this._resumeRecording(),
-            (triggerType) => this._activateTrigger(triggerType)
-        )
-        // always have to check if the URL is blocked really early,
-        // or you risk getting stuck in a loop
-        if (this._urlTriggerMatching.urlBlocked && !isRecordingPausedEvent(rawEvent)) {
-            return
-        }
+            if (rawEvent.type === EventType.Meta) {
+                const href = this._maskUrl(rawEvent.data.href)
+                this._lastHref = href
+                if (!href) {
+                    return
+                }
+                rawEvent.data.href = href
+            } else {
+                this._pageViewFallBack()
+            }
 
-        // we're processing a full snapshot, so we should reset the timer
-        if (rawEvent.type === EventType.FullSnapshot) {
-            this._scheduleFullSnapshot()
-            // Full snapshots reset rrweb's node IDs, so clear any logged node tracking
-            this._mutationThrottler?.reset()
-        }
+            // Check if the URL matches any trigger patterns
+            this._urlTriggerMatching.checkUrlTriggerConditions(
+                () => this._pauseRecording(),
+                () => this._resumeRecording(),
+                (triggerType) => this._activateTrigger(triggerType)
+            )
+            // always have to check if the URL is blocked really early,
+            // or you risk getting stuck in a loop
+            if (this._urlTriggerMatching.urlBlocked && !isRecordingPausedEvent(rawEvent)) {
+                return
+            }
 
-        // Clear the buffer if waiting for a trigger and only keep data from after the current full snapshot
-        // we always start trigger pending so need to wait for flags before we know if we're really pending
-        if (
-            rawEvent.type === EventType.FullSnapshot &&
-            this._triggerMatching.triggerStatus(this.sessionId) === TRIGGER_PENDING
-        ) {
-            this._clearBufferBeforeMostRecentMeta()
-        }
+            // we're processing a full snapshot, so we should reset the timer
+            if (rawEvent.type === EventType.FullSnapshot) {
+                this._scheduleFullSnapshot()
+                // Full snapshots reset rrweb's node IDs, so clear any logged node tracking
+                this._mutationThrottler?.reset()
+            }
 
-        const throttledEvent = this._mutationThrottler ? this._mutationThrottler.throttleMutations(rawEvent) : rawEvent
+            // Clear the buffer if waiting for a trigger and only keep data from after the current full snapshot
+            // we always start trigger pending so need to wait for flags before we know if we're really pending
+            if (
+                rawEvent.type === EventType.FullSnapshot &&
+                this._triggerMatching.triggerStatus(this.sessionId) === TRIGGER_PENDING
+            ) {
+                this._clearBufferBeforeMostRecentMeta()
+            }
 
-        if (!throttledEvent) {
-            return
-        }
+            const throttledEvent = this._mutationThrottler
+                ? this._mutationThrottler.throttleMutations(rawEvent)
+                : rawEvent
 
-        // TODO: Re-add ensureMaxMessageSize once we are confident in it
-        const event = truncateLargeConsoleLogs(throttledEvent)
+            if (!throttledEvent) {
+                return
+            }
 
-        this._updateWindowAndSessionIds(event)
+            // TODO: Re-add ensureMaxMessageSize once we are confident in it
+            const event = truncateLargeConsoleLogs(throttledEvent)
 
-        // When in an idle state we keep recording but don't capture the events,
-        // we don't want to return early if idle is 'unknown'
-        if (this._isIdle === true && !isSessionIdleEvent(event)) {
-            return
-        }
+            this._updateWindowAndSessionIds(event)
 
-        if (isSessionIdleEvent(event)) {
-            // session idle events have a timestamp when rrweb sees them
-            // which can artificially lengthen a session
-            // we know when we detected it based on the payload and can correct the timestamp
-            const payload = event.data.payload as SessionIdlePayload
-            if (payload) {
-                const lastActivity = payload.lastActivityTimestamp
-                const threshold = payload.threshold
-                event.timestamp = lastActivity + threshold
+            // When in an idle state we keep recording but don't capture the events,
+            // we don't want to return early if idle is 'unknown'
+            if (this._isIdle === true && !isSessionIdleEvent(event)) {
+                return
             }
-        }
 
-        const eventToSend =
-            (this._instance.config.session_recording?.compress_events ?? true) ? compressEvent(event) : event
-        const size = estimateSize(eventToSend)
+            if (isSessionIdleEvent(event)) {
+                // session idle events have a timestamp when rrweb sees them
+                // which can artificially lengthen a session
+                // we know when we detected it based on the payload and can correct the timestamp
+                const payload = event.data.payload as SessionIdlePayload
+                if (payload) {
+                    const lastActivity = payload.lastActivityTimestamp
+                    const threshold = payload.threshold
+                    event.timestamp = lastActivity + threshold
+                }
+            }
 
-        const properties = {
-            $snapshot_bytes: size,
-            $snapshot_data: eventToSend,
-            $session_id: this._sessionId,
-            $window_id: this._windowId,
-        }
+            const eventToSend =
+                (this._instance.config.session_recording?.compress_events ?? true) ? compressEvent(event) : event
+            const size = estimateSize(eventToSend)
 
-        if (this.status === DISABLED) {
-            this._clearBuffer()
-            return
-        }
+            const properties = {
+                $snapshot_bytes: size,
+                $snapshot_data: eventToSend,
+                $session_id: this._sessionId,
+                $window_id: this._windowId,
+            }
 
-        this._captureSnapshotBuffered(properties)
+            if (this.status === DISABLED) {
+                this._clearBuffer()
+                return
+            }
+
+            this._captureSnapshotBuffered(properties)
+        } catch (e) {
+            logger.error('error processing rrweb event', e)
+        }
     }
 
     get status(): SessionRecordingStatus {
@@ -1047,6 +1101,17 @@ export class LazyLoadedSessionRecording {
             return this._buffer
         }
 
+        if (!this._canCaptureSnapshots()) {
+            if (!this._loggedMissingEndpointFor) {
+                this._loggedMissingEndpointFor = true
+                logger.warn('snapshot capture skipped because requestRouter.endpointFor is unavailable')
+            }
+            this._flushBufferTimer = setTimeout(() => {
+                this._flushBuffer()
+            }, RECORDING_BUFFER_TIMEOUT)
+            return this._buffer
+        }
+
         if (this._buffer.data.length > 0) {
             const snapshotEvents = splitBuffer(this._buffer)
             snapshotEvents.forEach((snapshotBuffer) => {
@@ -1086,13 +1151,26 @@ export class LazyLoadedSessionRecording {
     }
 
     private _captureSnapshot(properties: Properties) {
-        // :TRICKY: Make sure we batch these requests, use a custom endpoint and don't truncate the strings.
-        this._instance.capture('$snapshot', properties, {
-            _url: this._instance.requestRouter.endpointFor('api', this._endpoint),
-            _noTruncate: true,
-            _batchKey: SESSION_RECORDING_BATCH_KEY,
-            skip_client_rate_limiting: true,
-        })
+        const url = this._snapshotIngestionUrl()
+        if (!url) {
+            if (!this._loggedMissingEndpointFor) {
+                this._loggedMissingEndpointFor = true
+                logger.warn('snapshot capture skipped because requestRouter.endpointFor is unavailable')
+            }
+            return
+        }
+
+        try {
+            // :TRICKY: Make sure we batch these requests, use a custom endpoint and don't truncate the strings.
+            this._instance.capture('$snapshot', properties, {
+                _url: url,
+                _noTruncate: true,
+                _batchKey: SESSION_RECORDING_BATCH_KEY,
+                skip_client_rate_limiting: true,
+            })
+        } catch (e) {
+            logger.error('failed to capture snapshot', e)
+        }
     }
 
     private _snapshotUrl(): string {
@@ -1418,13 +1496,23 @@ export class LazyLoadedSessionRecording {
             })
 
         const activePlugins = this._gatherRRWebPlugins()
-        this._stopRrweb = rrwebRecord({
-            emit: (event) => {
-                this.onRRwebEmit(event)
-            },
-            plugins: activePlugins,
-            ...sessionRecordingOptions,
-        })
+        try {
+            this._stopRrweb = rrwebRecord({
+                emit: (event) => {
+                    try {
+                        this.onRRwebEmit(event)
+                    } catch (e) {
+                        logger.error('error in rrweb emit handler', e)
+                    }
+                },
+                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/external/mutation-throttler.ts

@@ -54,7 +54,17 @@ export class MutationThrottler {
         return [id, node]
     }
 
-    private _getNode = (id: number) => this._rrweb.mirror.getNode(id)
+    private _getNode = (id: number | null | undefined): Node | null => {
+        // eslint-disable-next-line posthog-js/no-direct-undefined-check, posthog-js/no-direct-null-check
+        if (id === null || id === undefined) {
+            return null
+        }
+        try {
+            return this._rrweb.mirror.getNode(id) ?? null
+        } catch {
+            return null
+        }
+    }
 
     private _numberOfChanges = (data: Partial<mutationCallbackParam>) => {
         return (
@@ -66,36 +76,39 @@ export class MutationThrottler {
     }
 
     public throttleMutations = (event: eventWithTime) => {
-        if (event.type !== INCREMENTAL_SNAPSHOT_EVENT_TYPE || event.data.source !== MUTATION_SOURCE_TYPE) {
-            return event
-        }
-
-        const data = event.data as Partial<mutationCallbackParam>
-        const initialMutationCount = this._numberOfChanges(data)
-
-        if (data.attributes) {
-            // Most problematic mutations come from attrs where the style or minor properties are changed rapidly
-            data.attributes = data.attributes.filter((attr) => {
-                const [nodeId] = this._getNodeOrRelevantParent(attr.id)
-
-                const isRateLimited = this._rateLimiter.consumeRateLimit(nodeId)
-
-                if (isRateLimited) {
-                    return false
-                }
+        try {
+            if (event.type !== INCREMENTAL_SNAPSHOT_EVENT_TYPE || event.data.source !== MUTATION_SOURCE_TYPE) {
+                return event
+            }
 
-                return attr
-            })
-        }
+            const data = event.data as Partial<mutationCallbackParam>
+            const initialMutationCount = this._numberOfChanges(data)
+
+            if (data.attributes) {
+                // Most problematic mutations come from attrs where the style or minor properties are changed rapidly
+                data.attributes = data.attributes.filter((attr: any) => {
+                    const id = (attr as any)?.id
+                    if (typeof id !== 'number') {
+                        return true
+                    }
+
+                    const [nodeId] = this._getNodeOrRelevantParent(id)
+                    const isRateLimited = this._rateLimiter.consumeRateLimit(nodeId)
+                    return !isRateLimited
+                })
+            }
 
-        // Check if every part of the mutation is empty in which case there is nothing to do
-        const mutationCount = this._numberOfChanges(data)
+            // Check if every part of the mutation is empty in which case there is nothing to do
+            const mutationCount = this._numberOfChanges(data)
 
-        if (mutationCount === 0 && initialMutationCount !== mutationCount) {
-            // If we have modified the mutation count and the remaining count is 0, then we don't need the event.
-            return
+            if (mutationCount === 0 && initialMutationCount !== mutationCount) {
+                // If we have modified the mutation count and the remaining count is 0, then we don't need the event.
+                return
+            }
+            return event
+        } catch {
+            return event
         }
-        return event
     }
 
     public reset() {

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

@@ -213,22 +213,29 @@ export class SessionRecording {
         // If extensions provide an init function, use it. Otherwise, fall back to the local LazyLoadedSessionRecording
         if (assignableWindow.__PosthogExtensions__?.initSessionRecording) {
             if (!this._lazyLoadedSessionRecording) {
-                this._lazyLoadedSessionRecording = assignableWindow.__PosthogExtensions__?.initSessionRecording(
-                    this._instance
-                )
-                ;(this._lazyLoadedSessionRecording as any)._forceAllowLocalhostNetworkCapture =
-                    this._forceAllowLocalhostNetworkCapture
+                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'
+                    )
+                }
             }
 
-            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))
+            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)
                 }
-            } catch (e: any) {
-                logger.error('error starting session recording', e)
+                return
             }
-            return
         }
 
         if (!this._lazyLoadedSessionRecording) {