@leanbase-giangnd/js 0.2.4 → 0.3.1

package/dist/index.d.ts

@@ -1381,29 +1381,17 @@ declare class SessionRecording$1 {
     private readonly _instance;
     _forceAllowLocalhostNetworkCapture: boolean;
     private _receivedFlags;
-    private _serverRecordingEnabled;
     private _persistFlagsOnSessionListener;
     private _lazyLoadedSessionRecording;
     get started(): boolean;
-    /**
-     * 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$1;
     constructor(_instance: Leanbase);
     private get _isRecordingEnabled();
     startIfEnabledOrStop(startReason?: SessionStartReason$1): void;
-    /**
-     * 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;
     stopRecording(): void;
     private _resetSampling;
     private _persistRemoteConfig;
-    private _clearRemoteConfig;
     onRemoteConfig(response: RemoteConfig$1): void;
     log(message: string, level?: 'log' | 'warn' | 'error'): void;
     private get _scriptName();
@@ -1414,36 +1402,10 @@ declare class SessionRecording$1 {
      * @deprecated
      */
     onRRwebEmit(rawEvent: eventWithTime$1): void;
-    /**
-     * 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})`
-     * */
     overrideLinkedFlag(): void;
-    /**
-     * 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})`
-     * */
     overrideSampling(): void;
-    /**
-     * 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'})`
-     * */
     overrideTrigger(triggerType: TriggerType$1): void;
     get sdkDebugProperties(): Properties$1;
-    /**
-     * 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;
 }
 

package/dist/index.mjs

@@ -1169,7 +1169,7 @@ const detectDeviceType = function (user_agent) {
   }
 };
 
-var version = "0.2.4";
+var version = "0.3.1";
 var packageInfo = {
 	version: version};
 
@@ -3108,117 +3108,20 @@ const isLikelyBot = function (navigator, customBlockedUserAgents) {
 };
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
-// 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 = null;
-async function _loadRRWebModule() {
-  if (_cachedRRWeb) return _cachedRRWeb;
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const mod = await import('@rrweb/record');
-    _cachedRRWeb = mod;
-    return _cachedRRWeb;
-  } catch (e) {
-    return null;
-  }
-}
-// queue for method calls before rrweb loads
-const _queuedCalls = [];
-// Create a proxy function that delegates to the real rrweb.record when called
-const rrwebRecordProxy = function (...args) {
-  let realStop;
-  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, payload) {
-  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);
-};
-// Use a safe global target (prefer `win`, fallback to globalThis)
 const _target = win ?? globalThis;
 _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
-};
-// Provide initSessionRecording if not present — return a new LazyLoadedSessionRecording when called
+_target.__PosthogExtensions__.rrweb = _target.__PosthogExtensions__.rrweb || {};
 _target.__PosthogExtensions__.initSessionRecording = _target.__PosthogExtensions__.initSessionRecording || (instance => {
   const factory = _target.__PosthogExtensions__._initSessionRecordingFactory;
   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, scriptName, cb) => {
   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);
 
 // Type definitions copied from @rrweb/types@2.0.0-alpha.17 and rrweb-snapshot@2.0.0-alpha.17
@@ -3889,10 +3792,8 @@ class MutationThrottler {
         return event;
       }
     };
-    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
@@ -4088,6 +3989,23 @@ class LazyLoadedSessionRecording {
   get sessionId() {
     return this._sessionId;
   }
+  _disablePermanently(reason, error) {
+    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}`);
+      }
+    }
+  }
   get _sessionManager() {
     if (!this._instance.sessionManager) {
       throw new Error(LOGGER_PREFIX$1 + ' must be started with a valid sessionManager.');
@@ -4119,6 +4037,8 @@ class LazyLoadedSessionRecording {
      */
     this._forceAllowLocalhostNetworkCapture = false;
     this._stopRrweb = undefined;
+    this._permanentlyDisabled = false;
+    this._loggedPermanentlyDisabled = false;
     this._lastActivityTimestamp = Date.now();
     /**
      * and a queue - that contains rrweb events that we want to send to rrweb, but rrweb wasn't able to accept them yet
@@ -4308,6 +4228,9 @@ class LazyLoadedSessionRecording {
     }
   }
   _tryAddCustomEvent(tag, payload) {
+    if (!this.isStarted || !this._recording) {
+      return false;
+    }
     const rrwebRecord = getRRWebRecord();
     if (!rrwebRecord || typeof rrwebRecord.addCustomEvent !== 'function') {
       return false;
@@ -4337,6 +4260,10 @@ class LazyLoadedSessionRecording {
     }
   }
   _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.
@@ -4358,6 +4285,9 @@ class LazyLoadedSessionRecording {
     }
   }
   _tryTakeFullSnapshot() {
+    if (!this.isStarted || !this._recording) {
+      return false;
+    }
     const rrwebRecord = getRRWebRecord();
     if (!rrwebRecord || typeof rrwebRecord.takeFullSnapshot !== 'function') {
       return false;
@@ -4371,6 +4301,9 @@ class LazyLoadedSessionRecording {
     return this._instance.config.session_recording?.full_snapshot_interval_millis ?? FIVE_MINUTES;
   }
   _scheduleFullSnapshot() {
+    if (!this.isStarted || !this._recording) {
+      return;
+    }
     if (this._fullSnapshotTimer) {
       clearInterval(this._fullSnapshotTimer);
     }
@@ -4387,6 +4320,9 @@ class LazyLoadedSessionRecording {
     }, interval);
   }
   _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;
@@ -4404,6 +4340,9 @@ class LazyLoadedSessionRecording {
     });
   }
   _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;
@@ -4417,6 +4356,9 @@ class LazyLoadedSessionRecording {
     logger.info('recording resumed');
   }
   _activateTrigger(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({
@@ -4427,7 +4369,7 @@ class LazyLoadedSessionRecording {
     }
   }
   get isStarted() {
-    return !!this._stopRrweb;
+    return !!this._recording?.stop;
   }
   get _remoteConfig() {
     const persistedConfig = this._instance.get_property(SESSION_RECORDING_REMOTE_CONFIG);
@@ -4438,6 +4380,9 @@ class LazyLoadedSessionRecording {
     return parsedConfig;
   }
   async start(startReason) {
+    if (this._permanentlyDisabled) {
+      return;
+    }
     this._isFullyReady = false;
     const config = this._remoteConfig;
     if (!config) {
@@ -4463,8 +4408,14 @@ 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,
@@ -4472,12 +4423,8 @@ 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).
     this._isFullyReady = this._canCaptureSnapshots();
@@ -4556,7 +4503,8 @@ class LazyLoadedSessionRecording {
     this._mutationThrottler?.stop();
     // 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');
@@ -4576,8 +4524,12 @@ class LazyLoadedSessionRecording {
     return !!this._snapshotIngestionUrl();
   }
   onRRwebEmit(rawEvent) {
+    // 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;
     }
     try {
@@ -4682,6 +4634,9 @@ class LazyLoadedSessionRecording {
     });
   }
   overrideLinkedFlag() {
+    if (!this.isStarted || !this._recording || !this._isFullyReady) {
+      return;
+    }
     this._linkedFlagMatching.linkedFlagSeen = true;
     this._tryTakeFullSnapshot();
     this._reportStarted('linked_flag_overridden');
@@ -4693,6 +4648,9 @@ class LazyLoadedSessionRecording {
    * instead call `posthog.startSessionRecording({sampling: true})`
    * */
   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
@@ -4707,6 +4665,9 @@ class LazyLoadedSessionRecording {
    * instead call `posthog.startSessionRecording({trigger: 'url' | 'event'})`
    * */
   overrideTrigger(triggerType) {
+    if (!this.isStarted || !this._recording || !this._isFullyReady) {
+      return;
+    }
     this._activateTrigger(triggerType);
   }
   _clearFlushBufferTimer() {
@@ -4839,6 +4800,9 @@ class LazyLoadedSessionRecording {
     return this._buffer;
   }
   _reportStarted(startReason, tagPayload) {
+    if (!this.isStarted || !this._recording) {
+      return;
+    }
     this._instance.registerForSession({
       $session_recording_start_reason: startReason
     });
@@ -4982,7 +4946,7 @@ class LazyLoadedSessionRecording {
     };
   }
   async _startRecorder() {
-    if (this._stopRrweb) {
+    if (this._permanentlyDisabled || this._recording) {
       return;
     }
     // rrweb config info: https://github.com/rrweb-io/rrweb/blob/7d5d0033258d6c29599fb08412202d9a2c7b9413/src/record/index.ts#L28
@@ -5044,27 +5008,18 @@ class LazyLoadedSessionRecording {
       rrwebRecord = loaded ?? undefined;
     }
     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$1 + ' ' + message, 'warn');
-      }
-    });
     const activePlugins = this._gatherRRWebPlugins();
+    let stopHandler;
     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);
           }
         },
@@ -5072,10 +5027,30 @@ class LazyLoadedSessionRecording {
         ...sessionRecordingOptions
       });
     } 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$1 + ' ' + 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
@@ -5105,10 +5080,6 @@ class SessionRecording {
   get started() {
     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() {
     if (this._lazyLoadedSessionRecording) {
       return this._lazyLoadedSessionRecording.status;
@@ -5122,7 +5093,6 @@ class SessionRecording {
     this._instance = _instance;
     this._forceAllowLocalhostNetworkCapture = false;
     this._receivedFlags = false;
-    this._serverRecordingEnabled = false;
     this._persistFlagsOnSessionListener = undefined;
     if (!this._instance.sessionManager) {
       log.error('started without valid sessionManager');
@@ -5145,26 +5115,14 @@ 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
-   */
   _lazyLoadAndStart(startReason) {
-    // 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, err => {
@@ -5219,16 +5177,10 @@ 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);
     }
   }
-  _clearRemoteConfig() {
-    this._instance.persistence?.unregister(SESSION_RECORDING_REMOTE_CONFIG);
-    this._resetSampling();
-  }
   onRemoteConfig(response) {
     if (!('sessionRecording' in response)) {
       // if sessionRecording is not in the response, we do nothing
@@ -5237,12 +5189,8 @@ 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();
   }
@@ -5303,54 +5251,23 @@ class SessionRecording {
   onRRwebEmit(rawEvent) {
     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})`
-   * */
   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})`
-   * */
   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'})`
-   * */
   overrideTrigger(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() {
     return this._lazyLoadedSessionRecording?.sdkDebugProperties || {
       $recording_status: this.status
     };
   }
-  /**
-   * 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, payload) {
     return !!this._lazyLoadedSessionRecording?.tryAddCustomEvent(tag, payload);
   }