@leanbase.com/js 0.1.0 → 0.1.2

package/src/leanbase.ts

@@ -1,72 +1,195 @@
-import { PostHogCore, getFetch } from '@posthog/core'
+import {
+    PostHogCore,
+    getFetch,
+    isEmptyObject,
+    isEmptyString,
+    isNumber,
+    isObject,
+    isString,
+    isUndefined,
+} from '@posthog/core'
 import type {
-    PostHogCoreOptions,
     PostHogEventProperties,
     PostHogFetchOptions,
     PostHogFetchResponse,
     PostHogPersistedProperty,
-    PostHogCaptureOptions,
 } from '@posthog/core'
-import { version } from './version'
+import {
+    LeanbaseConfig,
+    LeanbasegCaptureOptions as LeanbaseCaptureOptions,
+    RemoteConfig,
+    CaptureResult,
+    Properties,
+} from './types'
+import { LeanbasePersistence } from './leanbase-persistence'
+import {
+    addEventListener,
+    copyAndTruncateStrings,
+    document,
+    extend,
+    isCrossDomainCookie,
+    navigator,
+    userAgent,
+} from './utils'
+import Config from './config'
+import { Autocapture } from './autocapture'
 import { logger } from './leanbase-logger'
-import { isNull } from '@posthog/core'
-
-export interface LeanbaseOptions extends Partial<PostHogCoreOptions> {
-    /**
-     * Enable autocapture of clicks and form interactions
-     * @default true
-     */
-    autocapture?: boolean
+import { COOKIELESS_MODE_FLAG_PROPERTY, USER_STATE } from './constants'
+import { getEventProperties } from './utils/event-utils'
+import { SessionIdManager } from './sessionid'
+import { SessionPropsManager } from './session-props'
+import { uuidv7 } from './uuidv7'
+import { PageViewManager } from './page-view'
+import { ScrollManager } from './scroll-manager'
+import { isLikelyBot } from './utils/blocked-uas'
 
-    /**
-     * API host for Leanbase
-     * @default 'https://i.leanbase.co'
-     */
-    host?: string
-}
+const defaultConfig = (): LeanbaseConfig => ({
+    host: 'https://i.leanbase.co',
+    token: '',
+    autocapture: true,
+    rageclick: true,
+    persistence: 'localStorage+cookie',
+    capture_pageview: 'history_change',
+    capture_pageleave: 'if_capture_pageview',
+    persistence_name: '',
+    mask_all_element_attributes: false,
+    cookie_expiration: 365,
+    cross_subdomain_cookie: isCrossDomainCookie(document?.location),
+    custom_campaign_params: [],
+    custom_personal_data_properties: [],
+    disable_persistence: false,
+    mask_personal_data_properties: false,
+    secure_cookie: window?.location?.protocol === 'https:',
+    mask_all_text: false,
+    bootstrap: {},
+    session_idle_timeout_seconds: 30 * 60,
+    save_campaign_params: true,
+    save_referrer: true,
+    opt_out_useragent_filter: false,
+    properties_string_max_length: 65535,
+    loaded: () => {},
+})
 
 export class Leanbase extends PostHogCore {
-    private _storage: Map<string, any> = new Map()
-    private _storageKey: string
+    config: LeanbaseConfig
+    scrollManager: ScrollManager
+    pageViewManager: PageViewManager
 
-    constructor(apiKey: string, options?: LeanbaseOptions) {
-        // Leanbase defaults
-        const leanbaseOptions: PostHogCoreOptions = {
-            host: 'https://i.leanbase.co',
-            ...options,
-        }
+    replayAutocapture?: Autocapture
+    persistence?: LeanbasePersistence
+    sessionPersistence?: LeanbasePersistence
+    sessionManager?: SessionIdManager
+    sessionPropsManager?: SessionPropsManager
+    isRemoteConfigLoaded?: boolean
+    personProcessingSetOncePropertiesSent = false
+    isLoaded: boolean = false
+    initialPageviewCaptured: boolean
+    visibilityStateListener: (() => void) | null
+
+    constructor(token: string, config?: Partial<LeanbaseConfig>) {
+        const mergedConfig = extend(defaultConfig(), config || {}, {
+            token,
+        })
+        super(token, mergedConfig)
+        this.config = mergedConfig as LeanbaseConfig
+        this.visibilityStateListener = null
+        this.initialPageviewCaptured = false
+        this.scrollManager = new ScrollManager(this)
+        this.pageViewManager = new PageViewManager(this)
+        this.init(token, mergedConfig)
+    }
 
-        super(apiKey, leanbaseOptions)
+    init(token: string, config: Partial<LeanbaseConfig>) {
+        this.setConfig(
+            extend(defaultConfig(), config, {
+                token,
+            })
+        )
+        this.isLoaded = true
+        this.persistence = new LeanbasePersistence(this.config)
+        this.replayAutocapture = new Autocapture(this)
+        this.replayAutocapture.startIfEnabled()
 
-        this._storageKey = `leanbase_${apiKey}`
+        if (this.config.preloadFeatureFlags !== false) {
+            this.reloadFeatureFlags()
+        }
 
-        // Load from localStorage if available
-        if (typeof window !== 'undefined' && window.localStorage) {
-            try {
-                const stored = window.localStorage.getItem(this._storageKey)
-                if (stored) {
-                    const parsed = JSON.parse(stored)
-                    Object.entries(parsed).forEach(([key, value]) => {
-                        this._storage.set(key, value)
-                    })
+        this.config.loaded?.(this)
+        if (this.config.capture_pageview) {
+            setTimeout(() => {
+                if (this.config.cookieless_mode === 'always') {
+                    this.captureInitialPageview()
                 }
-            } catch (err) {
-                logger.warn('Failed to load persisted data', err)
+            }, 1)
+        }
+
+        addEventListener(document, 'DOMContentLoaded', () => {
+            this.loadRemoteConfig()
+        })
+        addEventListener(window, 'onpagehide' in self ? 'pagehide' : 'unload', this.capturePageLeave.bind(this), {
+            passive: false,
+        })
+    }
+
+    captureInitialPageview(): void {
+        if (!document) {
+            return
+        }
+
+        if (document.visibilityState !== 'visible') {
+            if (!this.visibilityStateListener) {
+                this.visibilityStateListener = this.captureInitialPageview.bind(this)
+                addEventListener(document, 'visibilitychange', this.visibilityStateListener)
             }
+
+            return
         }
 
-        logger.info('Leanbase initialized', { apiKey, host: leanbaseOptions.host })
+        if (!this.initialPageviewCaptured) {
+            this.initialPageviewCaptured = true
+            this.capture('$pageview', { title: document.title })
 
-        // Preload feature flags if not explicitly disabled
-        if (options?.preloadFeatureFlags !== false) {
-            this.reloadFeatureFlags()
+            if (this.visibilityStateListener) {
+                document.removeEventListener('visibilitychange', this.visibilityStateListener)
+                this.visibilityStateListener = null
+            }
+        }
+    }
+
+    capturePageLeave() {
+        const { capture_pageleave, capture_pageview } = this.config
+        if (
+            capture_pageleave === true ||
+            (capture_pageleave === 'if_capture_pageview' &&
+                (capture_pageview === true || capture_pageview === 'history_change'))
+        ) {
+            this.capture('$pageleave')
         }
     }
 
-    // PostHogCore abstract methods
+    async loadRemoteConfig() {
+        if (!this.isRemoteConfigLoaded) {
+            const remoteConfig = await this.reloadRemoteConfigAsync()
+            if (remoteConfig) {
+                this.onRemoteConfig(remoteConfig as RemoteConfig)
+            }
+        }
+    }
+
+    onRemoteConfig(config: RemoteConfig): void {
+        if (!(document && document.body)) {
+            setTimeout(() => {
+                this.onRemoteConfig(config)
+            }, 500)
+            return
+        }
+
+        this.isRemoteConfigLoaded = true
+        this.replayAutocapture?.onRemoteConfig(config)
+    }
+
     fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse> {
         const fetchFn = getFetch()
-
         if (!fetchFn) {
             return Promise.reject(new Error('Fetch API is not available in this environment.'))
         }
@@ -74,12 +197,26 @@ export class Leanbase extends PostHogCore {
         return fetchFn(url, options)
     }
 
+    setConfig(config: Partial<LeanbaseConfig>): void {
+        const oldConfig = { ...this.config }
+        if (isObject(config)) {
+            extend(this.config, config)
+            this.persistence?.update_config(this.config, oldConfig)
+            this.replayAutocapture?.startIfEnabled()
+        }
+
+        const isTempStorage = this.config.persistence === 'sessionStorage' || this.config.persistence === 'memory'
+        this.sessionPersistence = isTempStorage
+            ? this.persistence
+            : new LeanbasePersistence({ ...this.config, persistence: 'sessionStorage' })
+    }
+
     getLibraryId(): string {
         return 'leanbase'
     }
 
     getLibraryVersion(): string {
-        return version
+        return Config.LIB_VERSION
     }
 
     getCustomUserAgent(): void {
@@ -87,43 +224,201 @@ export class Leanbase extends PostHogCore {
     }
 
     getPersistedProperty<T>(key: PostHogPersistedProperty): T | undefined {
-        return this._storage.get(key)
+        return this.persistence?.get_property(key)
     }
 
     setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void {
-        if (isNull(value)) {
-            this._storage.delete(key)
-        } else {
-            this._storage.set(key, value)
-        }
-
-        // Persist to localStorage if available
-        if (typeof window !== 'undefined' && window.localStorage) {
-            try {
-                const obj: Record<string, any> = {}
-                this._storage.forEach((v, k) => {
-                    obj[k] = v
-                })
-                window.localStorage.setItem(this._storageKey, JSON.stringify(obj))
-            } catch (err) {
-                logger.warn('Failed to persist data', err)
+        this.persistence?.set_property(key, value)
+    }
+
+    calculateEventProperties(
+        eventName: string,
+        eventProperties: PostHogEventProperties,
+        timestamp: Date,
+        uuid: string,
+        readOnly?: boolean
+    ): Properties {
+        if (!this.persistence || !this.sessionPersistence) {
+            return eventProperties
+        }
+
+        timestamp = timestamp || new Date()
+        const startTimestamp = readOnly ? undefined : this.persistence?.remove_event_timer(eventName)
+        let properties = { ...eventProperties }
+        properties['token'] = this.config.token
+        if (this.config.cookieless_mode == 'always' || this.config.cookieless_mode == 'on_reject') {
+            properties[COOKIELESS_MODE_FLAG_PROPERTY] = true
+        }
+
+        if (eventName === '$snapshot') {
+            const persistenceProps = { ...this.persistence.properties() }
+            properties['distinct_id'] = persistenceProps.distinct_id
+            if (
+                !(isString(properties['distinct_id']) || isNumber(properties['distinct_id'])) ||
+                isEmptyString(properties['distinct_id'])
+            ) {
+                logger.error('Invalid distinct_id for replay event. This indicates a bug in your implementation')
             }
+            return properties
+        }
+
+        const infoProperties = getEventProperties(
+            this.config.mask_personal_data_properties,
+            this.config.custom_personal_data_properties
+        )
+
+        if (this.sessionManager) {
+            const { sessionId, windowId } = this.sessionManager.checkAndGetSessionAndWindowId(
+                readOnly,
+                timestamp.getTime()
+            )
+            properties['$session_id'] = sessionId
+            properties['$window_id'] = windowId
+        }
+
+        if (this.sessionPropsManager) {
+            extend(properties, this.sessionPropsManager.getSessionProps())
         }
+
+        let pageviewProperties: Record<string, any> = this.pageViewManager.doEvent()
+        if (eventName === '$pageview' && !readOnly) {
+            pageviewProperties = this.pageViewManager.doPageView(timestamp, uuid)
+        }
+
+        if (eventName === '$pageleave' && !readOnly) {
+            pageviewProperties = this.pageViewManager.doPageLeave(timestamp)
+        }
+
+        properties = extend(properties, pageviewProperties)
+
+        if (eventName === '$pageview' && document) {
+            properties['title'] = document.title
+        }
+
+        if (!isUndefined(startTimestamp)) {
+            const duration_in_ms = timestamp.getTime() - startTimestamp
+            properties['$duration'] = parseFloat((duration_in_ms / 1000).toFixed(3))
+        }
+
+        if (userAgent && this.config.opt_out_useragent_filter) {
+            properties['$browser_type'] = isLikelyBot(navigator, []) ? 'bot' : 'browser'
+        }
+
+        properties = extend(
+            {},
+            infoProperties,
+            this.persistence.properties(),
+            this.sessionPersistence.properties(),
+            properties
+        )
+
+        properties['$is_identified'] = this.isIdentified()
+        return properties
+    }
+
+    isIdentified(): boolean {
+        return (
+            this.persistence?.get_property(USER_STATE) === 'identified' ||
+            this.sessionPersistence?.get_property(USER_STATE) === 'identified'
+        )
+    }
+
+    /**
+     * Add additional set_once properties to the event when creating a person profile. This allows us to create the
+     * profile with mostly-accurate properties, despite earlier events not setting them. We do this by storing them in
+     * persistence.
+     * @param dataSetOnce
+     */
+    calculateSetOnceProperties(dataSetOnce?: Properties): Properties | undefined {
+        if (!this.persistence) {
+            return dataSetOnce
+        }
+
+        if (this.personProcessingSetOncePropertiesSent) {
+            return dataSetOnce
+        }
+
+        const initialProps = this.persistence.get_initial_props()
+        const sessionProps = this.sessionPropsManager?.getSetOnceProps()
+        const setOnceProperties = extend({}, initialProps, sessionProps || {}, dataSetOnce || {})
+        this.personProcessingSetOncePropertiesSent = true
+        if (isEmptyObject(setOnceProperties)) {
+            return undefined
+        }
+
+        return setOnceProperties
     }
 
-    // Public API: leanbase.capture()
-    capture(event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void {
-        super.capture(event, properties, options)
+    capture(event: string, properties?: PostHogEventProperties, options?: LeanbaseCaptureOptions): void {
+        if (!this.isLoaded || !this.sessionPersistence || !this.persistence) {
+            return
+        }
+
+        if (isUndefined(event) || !isString(event)) {
+            logger.error('No event name provided to posthog.capture')
+            return
+        }
+
+        if (properties?.$current_url && !isString(properties?.$current_url)) {
+            logger.error(
+                'Invalid `$current_url` property provided to `posthog.capture`. Input must be a string. Ignoring provided value.'
+            )
+            delete properties?.$current_url
+        }
+
+        this.sessionPersistence.update_search_keyword()
+
+        if (this.config.save_campaign_params) {
+            this.sessionPersistence.update_campaign_params()
+        }
+
+        if (this.config.save_referrer) {
+            this.sessionPersistence.update_referrer_info()
+        }
+
+        if (this.config.save_campaign_params || this.config.save_referrer) {
+            this.persistence.set_initial_person_info()
+        }
+
+        const systemTime = new Date()
+        const timestamp = options?.timestamp || systemTime
+        const uuid = uuidv7()
+        let data: CaptureResult = {
+            uuid,
+            event,
+            properties: this.calculateEventProperties(event, properties || {}, timestamp, uuid),
+        }
+
+        const setProperties = options?.$set
+        if (setProperties) {
+            data.$set = options?.$set
+        }
+
+        const setOnceProperties = this.calculateSetOnceProperties(options?.$set_once)
+        if (setOnceProperties) {
+            data.$set_once = setOnceProperties
+        }
+
+        data = copyAndTruncateStrings(data, options?._noTruncate ? null : this.config.properties_string_max_length)
+        data.timestamp = timestamp
+        if (!isUndefined(options?.timestamp)) {
+            data.properties['$event_time_override_provided'] = true
+            data.properties['$event_time_override_system_time'] = systemTime
+        }
+
+        const finalSet = { ...data.properties['$set'], ...data['$set'] }
+        if (!isEmptyObject(finalSet)) {
+            this.setPersonPropertiesForFlags(finalSet)
+        }
+
+        super.capture(data.event, data.properties, options)
     }
 
-    // Public API: leanbase.identify()
-    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void {
+    identify(distinctId?: string, properties?: PostHogEventProperties, options?: LeanbaseCaptureOptions): void {
         super.identify(distinctId, properties, options)
     }
 
-    // Cleanup
     destroy(): void {
-        // Future: cleanup autocapture and session recording
-        this._storage.clear()
+        this.persistence?.clear()
     }
 }

package/src/page-view.ts

@@ -0,0 +1,124 @@
+import { window } from './utils'
+import { Leanbase } from './leanbase'
+import { clampToRange, isUndefined, Logger } from '@posthog/core'
+import { extend } from './utils'
+import { logger } from './leanbase-logger'
+
+interface PageViewEventProperties {
+    $pageview_id?: string
+    $prev_pageview_id?: string
+    $prev_pageview_pathname?: string
+    $prev_pageview_duration?: number // seconds
+    $prev_pageview_last_scroll?: number
+    $prev_pageview_last_scroll_percentage?: number
+    $prev_pageview_max_scroll?: number
+    $prev_pageview_max_scroll_percentage?: number
+    $prev_pageview_last_content?: number
+    $prev_pageview_last_content_percentage?: number
+    $prev_pageview_max_content?: number
+    $prev_pageview_max_content_percentage?: number
+}
+
+// This keeps track of the PageView state (such as the previous PageView's path, timestamp, id, and scroll properties).
+// We store the state in memory, which means that for non-SPA sites, the state will be lost on page reload. This means
+// that non-SPA sites should always send a $pageleave event on any navigation, before the page unloads. For SPA sites,
+// they only need to send a $pageleave event when the user navigates away from the site, as the information is not lost
+// on an internal navigation, and is included as the $prev_pageview_ properties in the next $pageview event.
+
+// Practically, this means that to find the scroll properties for a given pageview, you need to find the event where
+// event name is $pageview or $pageleave and where $prev_pageview_id matches the original pageview event's id.
+
+export class PageViewManager {
+    _currentPageview?: { timestamp: Date; pageViewId: string | undefined; pathname: string | undefined }
+    _instance: Leanbase
+
+    constructor(instance: Leanbase) {
+        this._instance = instance
+    }
+
+    doPageView(timestamp: Date, pageViewId?: string): PageViewEventProperties {
+        const response = this._previousPageViewProperties(timestamp, pageViewId)
+
+        // On a pageview we reset the contexts
+        this._currentPageview = { pathname: window?.location.pathname ?? '', pageViewId, timestamp }
+        this._instance.scrollManager.resetContext()
+
+        return response
+    }
+
+    doPageLeave(timestamp: Date): PageViewEventProperties {
+        return this._previousPageViewProperties(timestamp, this._currentPageview?.pageViewId)
+    }
+
+    doEvent(): PageViewEventProperties {
+        return { $pageview_id: this._currentPageview?.pageViewId }
+    }
+
+    private _previousPageViewProperties(timestamp: Date, pageviewId: string | undefined): PageViewEventProperties {
+        const previousPageView = this._currentPageview
+
+        if (!previousPageView) {
+            return { $pageview_id: pageviewId }
+        }
+
+        let properties: PageViewEventProperties = {
+            $pageview_id: pageviewId,
+            $prev_pageview_id: previousPageView.pageViewId,
+        }
+
+        const scrollContext = this._instance.scrollManager.getContext()
+
+        if (scrollContext && !this._instance.config.disable_scroll_properties) {
+            let { maxScrollHeight, lastScrollY, maxScrollY, maxContentHeight, lastContentY, maxContentY } =
+                scrollContext
+
+            if (
+                !isUndefined(maxScrollHeight) &&
+                !isUndefined(lastScrollY) &&
+                !isUndefined(maxScrollY) &&
+                !isUndefined(maxContentHeight) &&
+                !isUndefined(lastContentY) &&
+                !isUndefined(maxContentY)
+            ) {
+                // Use ceil, so that e.g. scrolling 999.5px of a 1000px page is considered 100% scrolled
+                maxScrollHeight = Math.ceil(maxScrollHeight)
+                lastScrollY = Math.ceil(lastScrollY)
+                maxScrollY = Math.ceil(maxScrollY)
+                maxContentHeight = Math.ceil(maxContentHeight)
+                lastContentY = Math.ceil(lastContentY)
+                maxContentY = Math.ceil(maxContentY)
+
+                // if the maximum scroll height is near 0, then the percentage is 1
+                const lastScrollPercentage =
+                    maxScrollHeight <= 1 ? 1 : clampToRange(lastScrollY / maxScrollHeight, 0, 1, logger as Logger)
+                const maxScrollPercentage =
+                    maxScrollHeight <= 1 ? 1 : clampToRange(maxScrollY / maxScrollHeight, 0, 1, logger as Logger)
+                const lastContentPercentage =
+                    maxContentHeight <= 1 ? 1 : clampToRange(lastContentY / maxContentHeight, 0, 1, logger as Logger)
+                const maxContentPercentage =
+                    maxContentHeight <= 1 ? 1 : clampToRange(maxContentY / maxContentHeight, 0, 1, logger as Logger)
+
+                properties = extend(properties, {
+                    $prev_pageview_last_scroll: lastScrollY,
+                    $prev_pageview_last_scroll_percentage: lastScrollPercentage,
+                    $prev_pageview_max_scroll: maxScrollY,
+                    $prev_pageview_max_scroll_percentage: maxScrollPercentage,
+                    $prev_pageview_last_content: lastContentY,
+                    $prev_pageview_last_content_percentage: lastContentPercentage,
+                    $prev_pageview_max_content: maxContentY,
+                    $prev_pageview_max_content_percentage: maxContentPercentage,
+                })
+            }
+        }
+
+        if (previousPageView.pathname) {
+            properties.$prev_pageview_pathname = previousPageView.pathname
+        }
+        if (previousPageView.timestamp) {
+            // Use seconds, for consistency with our other duration-related properties like $duration
+            properties.$prev_pageview_duration = (timestamp.getTime() - previousPageView.timestamp.getTime()) / 1000
+        }
+
+        return properties
+    }
+}