@safaricom-mxl/web-sdk 0.0.16 → 0.0.18

package/dist/managers/MXLUserSessionManager/MXLUserSessionManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"MXLUserSessionManager.cjs","names":["DEFAULT_ACTIVITY_THROTTLE_MS","DEFAULT_ACTIVITY_EVENTS","diag","readPermanentProperties","trace","throttle","clampNumber","DEFAULT_USER_SESSION_MAX_DURATION_SECONDS","MAX_USER_SESSION_MAX_DURATION_SECONDS","MIN_USER_SESSION_MAX_DURATION_SECONDS","DEFAULT_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS","MAX_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS","initTabContext","KEY_MXL_USER_SESSION_ID","ATTR_SESSION_ID","KEY_MXL_USER_SESSION_PREVIOUS_ID","ATTR_SESSION_PREVIOUS_ID","KEY_MXL_USER_SESSION_NUMBER","KEY_MXL_USER_SESSION_PART_INDEX","KEY_MXL_SESSION_PART_NUMBER","KEY_MXL_USER_SESSION_START_TS","KEY_MXL_USER_SESSION_MAX_DURATION_SECONDS","KEY_MXL_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS","MXL_LAST_END_USER_SESSION_TS_KEY","getVisibilityState","generateUUID","KEY_MXL_TYPE","KEY_MXL_STATE","KEY_MXL_SESSION_PART_ID","KEY_MXL_SESSION_PART_START_REASON","KEY_MXL_COLD_START","KEY_MXL_EXPERIENCE_ID","KEY_MXL_TAB_ID","KEY_MXL_NAVIGATION_SOURCE","KEY_MXL_REFERRER_URL","KEY_MXL_SOURCE_TAB_ID","MXLExtendedSpan","SESSION_PART_SPAN_NAME","KEY_MXL_SESSION_PART_END_REASON","KEY_MXL_SDK_STARTUP_DURATION","KEY_MXL_IS_FINAL_SESSION_PART","KEY_MXL_USER_SESSION_TERMINATION_REASON","KEY_PREFIX_MXL_PROPERTIES","MXL_USER_SESSION_STATE_KEY","storePermanentProperties","readUserSessionState","isUserSessionExpired","getIncrementedCount","MXL_USER_SESSION_NUMBER_KEY","createUserSessionState","MXL_SESSION_PART_NUMBER_KEY","isTabEngaged"],"sources":["../../../src/managers/MXLUserSessionManager/MXLUserSessionManager.ts"],"sourcesContent":["import type {\n  Attributes,\n  DiagLogger,\n  Tracer,\n  TracerProvider,\n} from '@opentelemetry/api';\nimport { diag, trace } from '@opentelemetry/api';\nimport {\n  ATTR_SESSION_ID,\n  ATTR_SESSION_PREVIOUS_ID,\n} from '@opentelemetry/semantic-conventions/incubating';\nimport type { ExtendedSpan } from '../../api-traces/api/TraceAPI/types';\nimport type {\n  PropertyOptions,\n  SessionPartEndReason,\n  SessionPartStartReason,\n  UserSessionEndReason,\n} from '../../api-sessions/manager/types';\nimport type { VisibilityStateDocument } from '../../common/types';\nimport { KEY_MXL_COLD_START, KEY_MXL_EXPERIENCE_ID, KEY_MXL_IS_FINAL_SESSION_PART, KEY_MXL_NAVIGATION_SOURCE, KEY_MXL_REFERRER_URL, KEY_MXL_SDK_STARTUP_DURATION, KEY_MXL_SESSION_PART_END_REASON, KEY_MXL_SESSION_PART_ID, KEY_MXL_SESSION_PART_NUMBER, KEY_MXL_SESSION_PART_START_REASON, KEY_MXL_SOURCE_TAB_ID, KEY_MXL_STATE, KEY_MXL_TAB_ID, KEY_MXL_TYPE, KEY_MXL_USER_SESSION_ID, KEY_MXL_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS, KEY_MXL_USER_SESSION_MAX_DURATION_SECONDS, KEY_MXL_USER_SESSION_NUMBER, KEY_MXL_USER_SESSION_PART_INDEX, KEY_MXL_USER_SESSION_PREVIOUS_ID, KEY_MXL_USER_SESSION_START_TS, KEY_MXL_USER_SESSION_TERMINATION_REASON, KEY_PREFIX_MXL_PROPERTIES, MXL_STATES, MXL_TYPES } from '../../constants/attributes';\nimport type { NamespacedStorage } from '../../utils/NamespacedStorage/NamespacedStorage';\nimport type { PerformanceManager } from '../../utils/PerformanceManager/types';\nimport type { TimeoutRef } from '../../utils/timeout/types';\nimport { clampNumber } from '../../utils/clampNumber';\nimport { generateUUID } from '../../utils/generateUUID';\nimport { getIncrementedCount } from '../../utils/getIncrementedCount';\nimport { getVisibilityState } from '../../utils/getVisibilityState';\nimport { throttle } from '../../utils/throttle';\nimport type { ThrottledFunction } from '../../utils/throttle';\nimport type { LimitManagerInternal } from '../MXLLimitManager/types';\nimport { MXLExtendedSpan } from '../MXLTraceManager/MXLExtendedSpan';\nimport {\n  DEFAULT_ACTIVITY_EVENTS,\n  DEFAULT_ACTIVITY_THROTTLE_MS,\n  DEFAULT_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS,\n  DEFAULT_USER_SESSION_MAX_DURATION_SECONDS,\n  END_USER_SESSION_COOLDOWN_MS,\n  MAX_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS,\n  MAX_USER_SESSION_MAX_DURATION_SECONDS,\n  MIN_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS,\n  MIN_USER_SESSION_MAX_DURATION_SECONDS,\n  MXL_LAST_END_USER_SESSION_TS_KEY,\n  MXL_SESSION_PART_NUMBER_KEY,\n  MXL_USER_SESSION_NUMBER_KEY,\n  MXL_USER_SESSION_STATE_KEY,\n  SESSION_PART_SPAN_NAME,\n} from './constants';\nimport type {\n  MXLUserSessionManagerArgs,\n  NavigationSource,\n  Tab,\n  UserSessionAttributes,\n  UserSessionManagerInternal,\n  UserSessionState,\n} from './types';\nimport { addActivityListeners, isTabEngaged, removeActivityListeners } from './utils/activity';\nimport { createUserSessionState, isUserSessionExpired, readPermanentProperties, readUserSessionState, storePermanentProperties } from './utils/state';\nimport { initTabContext, setupNewTabClickListeners } from './utils/tabTracking';\n\n/**\n * Parts are engagement-gated (visible AND focused), so only one part can\n * be active at a time. That mutex lets us treat storage as a\n * plain shared row read on engagement and written on changes.\n */\nexport class MXLUserSessionManager implements UserSessionManagerInternal {\n  private static readonly _testInstances = new Set<MXLUserSessionManager>();\n\n  /** @internal Test-only helper to tear down leaked managers between tests. */\n  public static shutdownAllTestInstances(): void {\n    for (const manager of MXLUserSessionManager._testInstances) {\n      manager._shutdown();\n    }\n    MXLUserSessionManager._testInstances.clear();\n  }\n\n  private _state: UserSessionState | null = null;\n  private _previousUserSessionId: string | null = null;\n  private readonly _maxUserSessionDurationSeconds: number;\n  private readonly _inactivityTimeoutSeconds: number;\n  private _maxDurationTimeout: ReturnType<typeof setTimeout> | null = null;\n  private _isShutdown = false;\n  // Bare keys; the wire-format prefix is applied at stamp time.\n  private _permanentProperties: Record<string, string> = {};\n  // Distinguishes \"another tab wiped storage after we wrote\" from \"we\n  // Never managed to write in the first place\"; see\n  // _continueUserSessionAfterPartEnd.\n  private _hasStoredState = false;\n\n  private _activeSessionPartId: string | null = null;\n  // Snapshotted at part start so a concurrent bump in another tab doesn't\n  // Shift this part's value before its span ends.\n  private _currentSessionPartNumber: number | null = null;\n  private _sessionPartSpan: ExtendedSpan | null = null;\n  private _activeSessionPartCounts: Record<string, number> | null = null;\n  // Marks the first part of the page lifetime so it can be reported as a\n  // Cold start.\n  private _coldStart = true;\n  private _nextSessionPartCounts: Record<string, number> = {};\n  private _sdkStartupDuration = 0;\n  private readonly _sessionPartStartedListeners: (() => void)[] = [];\n  private readonly _sessionPartEndedListeners: (() => void)[] = [];\n  private _tracer: Tracer;\n\n  private readonly _diag: DiagLogger;\n  private readonly _perf: PerformanceManager;\n  private readonly _storage: NamespacedStorage;\n  private readonly _visibilityDoc: VisibilityStateDocument;\n  private readonly _limitManager: LimitManagerInternal;\n  private readonly _target: EventTarget;\n  private readonly _activityEvents: readonly string[];\n  private readonly _onActivityThrottled: ThrottledFunction<\n    (event: Event) => void\n  >;\n  private _sessionPartInactivityTimer: TimeoutRef | null = null;\n  private readonly _tab: Tab;\n  private readonly _navigationSource: NavigationSource;\n  private readonly _referrerScrubbedUrl?: string;\n\n  public constructor({\n    config,\n    diag: diagParam,\n    perf,\n    visibilityDoc,\n    storage,\n    limitManager,\n    target = window,\n    activityThrottleMs = DEFAULT_ACTIVITY_THROTTLE_MS,\n    activityEvents = DEFAULT_ACTIVITY_EVENTS,\n    tabStorage,\n    referrer = typeof document !== 'undefined' ? document.referrer : '',\n    navigationPerformance = typeof window !== 'undefined'\n      ? window.performance\n      : { getEntriesByType: () => [] },\n  }: MXLUserSessionManagerArgs) {\n    this._diag =\n      diagParam ??\n      diag.createComponentLogger({\n        namespace: 'MXLUserSessionManager',\n      });\n    this._perf = perf;\n    this._visibilityDoc = visibilityDoc;\n    this._storage = storage;\n    this._limitManager = limitManager;\n    this._permanentProperties = readPermanentProperties(\n      this._storage,\n      this._diag,\n    );\n    this._tracer = trace.getTracer('mxl-web-sdk-session-parts');\n    this._target = target;\n    this._activityEvents = activityEvents;\n    this._onActivityThrottled = throttle(this._onActivity, activityThrottleMs);\n\n    const maxUserSessionDurationSeconds = clampNumber({\n      defaultValue: DEFAULT_USER_SESSION_MAX_DURATION_SECONDS,\n      diag: this._diag,\n      max: MAX_USER_SESSION_MAX_DURATION_SECONDS,\n      min: MIN_USER_SESSION_MAX_DURATION_SECONDS,\n      value: config?.maxUserSessionDurationSeconds,\n    });\n    const inactivityTimeoutSeconds = clampNumber({\n      defaultValue: DEFAULT_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS,\n      diag: this._diag,\n      max: MAX_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS,\n      min: MIN_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS,\n      value: config?.inactivityTimeoutSeconds,\n    });\n\n    this._maxUserSessionDurationSeconds = maxUserSessionDurationSeconds;\n    if (inactivityTimeoutSeconds <= maxUserSessionDurationSeconds) {\n      this._inactivityTimeoutSeconds = inactivityTimeoutSeconds;\n    } else {\n      this._diag.warn(\n        `inactivityTimeoutSeconds (${inactivityTimeoutSeconds.toString()}s) ` +\n          `exceeds maxUserSessionDurationSeconds (${maxUserSessionDurationSeconds.toString()}s); ` +\n          `falling back to default inactivity timeout (${DEFAULT_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS.toString()}s).`,\n      );\n      this._inactivityTimeoutSeconds =\n        DEFAULT_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS;\n    }\n\n    const tabContext = initTabContext({\n      diag: this._diag,\n      localStorage: storage,\n      navigationPerformance,\n      referrer,\n      sessionStorage: tabStorage,\n    });\n    this._tab = tabContext.tab;\n    this._navigationSource = tabContext.navigationSource;\n    this._referrerScrubbedUrl = tabContext.referrerScrubbedUrl;\n    setupNewTabClickListeners(this._tab, storage, this._diag);\n    MXLUserSessionManager._testInstances.add(this);\n  }\n\n  public setTracerProvider(tracerProvider: TracerProvider): void {\n    this._tracer = tracerProvider.getTracer('mxl-web-sdk-session-parts');\n    // Listeners attach here rather than in the constructor so that tests\n    // That construct a manager without going through SDK init don't\n    // Pollute window with listeners, and so that browser-activity-driven\n    // Parts only start once a real tracer is wired.\n    addActivityListeners({\n      activityEvents: this._activityEvents,\n      onActivity: this._onActivityThrottled,\n      onBlur: this._onBlur,\n      onFocus: this._onFocus,\n      onPageHide: this._onPageHide,\n      onPageShow: this._onPageShow,\n      onVisibilityChange: this._onVisibilityChange,\n      target: this._target,\n      visibilityDoc: this._visibilityDoc,\n    });\n    // Eager state init so getUserSessionId() returns a real id before the\n    // First part starts, and so other tabs see the row when we create a\n    // Fresh session here.\n    const { state, created } = this._loadOrCreateUserSessionState(\n      this._perf.getNowMillis(),\n    );\n    this._state = state;\n    if (created) {\n      this._storeState();\n    }\n  }\n\n  public recordSDKStartupDuration(duration: number): void {\n    this._sdkStartupDuration = Math.ceil(duration);\n  }\n\n  public getUserSessionId(): string | null {\n    return this._state?.userSessionId ?? null;\n  }\n\n  public getPreviousUserSessionId(): string | null {\n    // Fall back to in-memory for the brief window during user-session end\n    // Where storage is cleared but the just-ended id is still held.\n    return this._state?.previousUserSessionId ?? this._previousUserSessionId;\n  }\n\n  public getUserSessionStartTime(): number | null {\n    return this._state?.userSessionStartTs ?? null;\n  }\n\n  public getUserSessionAttributes(): UserSessionAttributes | null {\n    if (!this._state) {\n      return null;\n    }\n    const previousUserSessionId = this.getPreviousUserSessionId() ?? '';\n    return {\n      [KEY_MXL_USER_SESSION_ID]: this._state.userSessionId,\n      [ATTR_SESSION_ID]: this._state.userSessionId,\n      [KEY_MXL_USER_SESSION_PREVIOUS_ID]: previousUserSessionId,\n      [ATTR_SESSION_PREVIOUS_ID]: previousUserSessionId,\n      [KEY_MXL_USER_SESSION_NUMBER]: this._state.userSessionNumber,\n      [KEY_MXL_USER_SESSION_PART_INDEX]: this._state.userSessionPartIndex,\n      [KEY_MXL_SESSION_PART_NUMBER]: this._currentSessionPartNumber ?? 0,\n      [KEY_MXL_USER_SESSION_START_TS]: this._state.userSessionStartTs,\n      [KEY_MXL_USER_SESSION_MAX_DURATION_SECONDS]:\n        this._state.maxUserSessionDurationSeconds,\n      [KEY_MXL_USER_SESSION_INACTIVITY_TIMEOUT_SECONDS]:\n        this._state.inactivityTimeoutSeconds,\n    };\n  }\n\n  public endUserSession(): void {\n    if (!this._state) {\n      this._diag.debug(\n        'Trying to end user session, but there is no active session. This is a no-op.',\n      );\n      return;\n    }\n\n    const now = this._perf.getNowMillis();\n    const lastEndRaw = this._storage.getItem(MXL_LAST_END_USER_SESSION_TS_KEY);\n    const lastEndTs = lastEndRaw === null ? NaN : Number(lastEndRaw);\n    if (\n      Number.isFinite(lastEndTs) &&\n      now - lastEndTs < END_USER_SESSION_COOLDOWN_MS\n    ) {\n      this._diag.warn(\n        'endUserSession called within cooldown period, ignoring.',\n      );\n      return;\n    }\n\n    this._rolloverUserSession('manual');\n    this._storage.setItem(MXL_LAST_END_USER_SESSION_TS_KEY, String(now));\n  }\n\n  public getSessionPartId(): string | null {\n    return this._activeSessionPartId;\n  }\n\n  public getSessionPartSpan(): ExtendedSpan | null {\n    return this._sessionPartSpan;\n  }\n\n  public startSessionPartInternal(reason: SessionPartStartReason): void {\n    if (this._sessionPartSpan) {\n      this._diag.warn(\n        `startSessionPartInternal called while a part is active (reason: ${reason}); ignoring`,\n      );\n      return;\n    }\n\n    // Parts are foreground-only: a part corresponds to a tab that is both\n    // Visible AND focused.\n    if (\n      getVisibilityState(this._visibilityDoc) === MXL_STATES.Background ||\n      !this._visibilityDoc.hasFocus()\n    ) {\n      this._diag.debug(\n        `skipping session part start (reason: ${reason}) because the tab is not engaged`,\n      );\n      return;\n    }\n\n    const activeSessionPartId = generateUUID();\n    const previouslyRecordedCounts = this._nextSessionPartCounts;\n\n    this._beginUserSessionForPartStart();\n\n    const attributes: Attributes = {\n      ...this.getUserSessionAttributes(),\n      [KEY_MXL_TYPE]: MXL_TYPES.SessionPart,\n      [KEY_MXL_STATE]: MXL_STATES.Foreground,\n      [KEY_MXL_SESSION_PART_ID]: activeSessionPartId,\n      [KEY_MXL_SESSION_PART_START_REASON]: reason,\n      [KEY_MXL_COLD_START]: this._coldStart,\n      [KEY_MXL_EXPERIENCE_ID]: this._tab.experienceId,\n      [KEY_MXL_TAB_ID]: this._tab.tabId,\n      [KEY_MXL_NAVIGATION_SOURCE]: this._navigationSource,\n      ...previouslyRecordedCounts,\n    };\n\n    if (this._referrerScrubbedUrl) {\n      attributes[KEY_MXL_REFERRER_URL] = this._referrerScrubbedUrl;\n    }\n    if (this._tab.sourceTabId) {\n      attributes[KEY_MXL_SOURCE_TAB_ID] = this._tab.sourceTabId;\n    }\n\n    this._activeSessionPartId = activeSessionPartId;\n    let span: MXLExtendedSpan;\n    try {\n      span = new MXLExtendedSpan(\n        this._tracer.startSpan(SESSION_PART_SPAN_NAME, { attributes }),\n      );\n    } catch (error) {\n      this._activeSessionPartId = null;\n      this._diag.error('Error starting session part span', error);\n      return;\n    }\n\n    this._activeSessionPartCounts = {};\n    this._nextSessionPartCounts = {};\n    this._sessionPartSpan = span;\n    this._coldStart = false;\n\n    this._startSessionPartInactivityTimer();\n\n    this._fireListeners(this._sessionPartStartedListeners, 'started');\n  }\n\n  public endSessionPartInternal(\n    reason: SessionPartEndReason,\n    userSessionEndReason?: UserSessionEndReason | null,\n  ): void {\n    if (!this._sessionPartSpan) {\n      this._diag.debug(\n        'trying to end a session part, but there is no session part in progress. This is a no-op.',\n      );\n      return;\n    }\n\n    this._clearSessionPartInactivityTimer();\n\n    const isFinal = reason === 'user_session_ended' || reason === 'inactivity';\n\n    // Capture the end stamp upfront. SpanProcessor.onEnd can run unbounded\n    // And must not push it forward.\n    const partEndTs = this._perf.getNowMillis();\n    const span = this._sessionPartSpan;\n    try {\n      const endAttrs: Attributes = {\n        [KEY_MXL_SESSION_PART_END_REASON]: reason,\n        ...this._activeSessionPartCounts,\n        ...this._limitManager.getDiagnosticCounts(),\n        [KEY_MXL_SDK_STARTUP_DURATION]: this._sdkStartupDuration,\n      };\n      if (isFinal) {\n        endAttrs[KEY_MXL_IS_FINAL_SESSION_PART] = 1;\n        if (userSessionEndReason) {\n          endAttrs[KEY_MXL_USER_SESSION_TERMINATION_REASON] =\n            userSessionEndReason;\n        }\n      }\n\n      const propertyAttrs: Attributes = {};\n      for (const [bareKey, value] of Object.entries(\n        this.getSessionPartProperties(),\n      )) {\n        propertyAttrs[KEY_PREFIX_MXL_PROPERTIES + bareKey] = value;\n      }\n\n      try {\n        span.setAttributes({\n          ...propertyAttrs,\n          ...endAttrs,\n        });\n      } catch (error) {\n        this._diag.warn(\n          'Error setting end attributes on session part span; ending span without them',\n          error,\n        );\n      }\n    } finally {\n      // Fire listeners after end attributes are stamped (so subscribers can\n      // Read them) and before span.end() (so anything they emit still\n      // Attaches to the part that is conceptually still active).\n      this._fireListeners(this._sessionPartEndedListeners, 'ended');\n      try {\n        span.end(partEndTs);\n      } catch (error) {\n        this._diag.warn('Error ending session part span', error);\n      }\n      this._sessionPartSpan = null;\n      this._activeSessionPartId = null;\n      this._activeSessionPartCounts = null;\n      this._currentSessionPartNumber = null;\n      this._limitManager.reset();\n    }\n\n    if (isFinal) {\n      this._previousUserSessionId = this._state?.userSessionId ?? null;\n      this._state = null;\n      this._storage.removeItem(MXL_USER_SESSION_STATE_KEY);\n      this._clearMaxDurationTimer();\n    } else {\n      this._continueUserSessionAfterPartEnd(partEndTs);\n    }\n  }\n\n  public addBreadcrumb(name: string): void {\n    if (!this._sessionPartSpan) {\n      this._diag.debug(\n        'trying to add breadcrumb, but there is no session part in progress. This is a no-op.',\n      );\n      return;\n    }\n\n    const limitedBreadcrumb = this._limitManager.limitBreadcrumb(name);\n    if (limitedBreadcrumb === 'dropped') {\n      return;\n    }\n\n    this._sessionPartSpan.addEvent(\n      'mxl-breadcrumb',\n      {\n        message: limitedBreadcrumb.name,\n      },\n      this._perf.getNowMillis(),\n    );\n  }\n\n  public addProperty(\n    propertyKey: string,\n    value: string,\n    options?: PropertyOptions,\n  ): void {\n    const limitedSessionProperty = this._limitManager.limitSessionProperty(\n      propertyKey,\n      value,\n    );\n\n    if (limitedSessionProperty === 'dropped') {\n      return;\n    }\n\n    const bareKey = limitedSessionProperty.key;\n    const bareValue = limitedSessionProperty.value;\n\n    if (options?.lifespan === 'permanent') {\n      const candidate = {\n        ...this._permanentProperties,\n        [bareKey]: bareValue,\n      };\n      // Reject the write if storage is unavailable: a property that can't\n      // Persist would silently diverge from what other tabs (and the next\n      // Page load) see, which is worse than no property at all.\n      if (!storePermanentProperties(this._storage, candidate)) {\n        this._diag.warn(\n          'Storage unavailable; rejecting permanent property write.',\n        );\n        return;\n      }\n      this._permanentProperties = candidate;\n      this._removeFromUserSessionProperties(bareKey);\n      return;\n    }\n\n    // Ensure a state row exists so the write has somewhere to land;\n    // AddProperty can fire before any part has started.\n    const { state } = this._loadOrCreateUserSessionState(\n      this._perf.getNowMillis(),\n    );\n    this._state = {\n      ...state,\n      userSessionProperties: {\n        ...state.userSessionProperties,\n        [bareKey]: bareValue,\n      },\n    };\n    if (!this._storeState()) {\n      // Roll back so callers don't observe a value that won't persist.\n      // The user session itself stays in memory.\n      this._state = state;\n      this._diag.warn(\n        'Storage unavailable; rejecting user-session property write.',\n      );\n    }\n  }\n\n  public removeProperty(propertyKey: string): void {\n    const bareKey = this._limitManager.truncateString(\n      'session_property_key',\n      propertyKey,\n    );\n\n    // Try both stores so a key that was flipped between scopes doesn't\n    // Linger in the other one.\n    this._removeFromPermanentProperties(bareKey);\n    this._removeFromUserSessionProperties(bareKey);\n  }\n\n  /**\n   * Bare-keyed view of properties for the active part. User-session-scoped\n   * entries shadow permanent ones, matching the cross-scope flip rule\n   * enforced in `addProperty`. Callers apply the wire-format prefix at\n   * stamp time.\n   */\n  public getSessionPartProperties(): Record<string, string> {\n    return {\n      ...this._permanentProperties,\n      ...this._state?.userSessionProperties,\n    };\n  }\n\n  public incrSessionPartCountForKey(key: string): void {\n    if (!this._sessionPartSpan || !this._activeSessionPartCounts) {\n      this._diag.debug(\n        'trying to increment a count for the active session part, but there is no session part in progress. This is a no-op.',\n      );\n      return;\n    }\n    this._activeSessionPartCounts[key] =\n      (this._activeSessionPartCounts[key] || 0) + 1;\n  }\n\n  public incrNextSessionPartCountForKey(key: string): void {\n    this._nextSessionPartCounts[key] =\n      (this._nextSessionPartCounts[key] || 0) + 1;\n  }\n\n  public addSessionPartStartedListener(listener: () => void): () => void {\n    return this._addListener(this._sessionPartStartedListeners, listener);\n  }\n\n  public addSessionPartEndedListener(listener: () => void): () => void {\n    return this._addListener(this._sessionPartEndedListeners, listener);\n  }\n\n  /**\n   * Returns the persisted user-session state, rotating to a fresh one if\n   * the persisted row is missing or expired. Arms the max-duration timer\n   * when needed. The caller is responsible for assigning the result to\n   * `_state` and for persisting (the helper does not write to storage).\n   */\n  private _loadOrCreateUserSessionState(now: number): {\n    state: UserSessionState;\n    created: boolean;\n  } {\n    let state = readUserSessionState(this._storage, this._diag);\n    let created = false;\n    if (!state || isUserSessionExpired(state, now)) {\n      if (state) {\n        this._previousUserSessionId = state.userSessionId;\n      }\n      const userSessionNumber = getIncrementedCount(\n        this._storage,\n        MXL_USER_SESSION_NUMBER_KEY,\n        this._diag,\n      );\n      state = createUserSessionState({\n        inactivityTimeoutSeconds: this._inactivityTimeoutSeconds,\n        maxUserSessionDurationSeconds: this._maxUserSessionDurationSeconds,\n        now,\n        previousUserSessionId: this._previousUserSessionId,\n        userSessionNumber,\n      });\n      created = true;\n    }\n    // Arm on a freshly created state, and on the page-reload case where a\n    // New manager loads existing state and has no timer running yet.\n    // UserSessionMaxEndTs is fixed at creation, so re-arming the same value\n    // On every load/start call is wasteful.\n    if (created || this._maxDurationTimeout === null) {\n      this._setupMaxDurationTimer(state, now);\n    }\n    return { created, state };\n  }\n\n  /**\n   * Bumps the part counter and arms the max-duration timer. Relies on\n   * `_loadOrCreateUserSessionState` to provide a non-null, non-expired state,\n   * so `getUserSessionAttributes()` is guaranteed non-null after this.\n   */\n  private _beginUserSessionForPartStart(): void {\n    const now = this._perf.getNowMillis();\n    const { state } = this._loadOrCreateUserSessionState(now);\n\n    this._currentSessionPartNumber = getIncrementedCount(\n      this._storage,\n      MXL_SESSION_PART_NUMBER_KEY,\n      this._diag,\n    );\n\n    this._state = {\n      ...state,\n      userSessionPartIndex: state.userSessionPartIndex + 1,\n      // A part is active, so any pending inactivity deadline no longer\n      // Applies; it gets re-armed when the part ends.\n      inactivityDeadlineTs: null,\n    };\n    this._storeState();\n  }\n\n  /**\n   * Records the inactivity deadline on the user-session row so the next\n   * part start can detect lazy expiry. The max-duration timer stays valid\n   * because userSessionMaxEndTs doesn't change between parts.\n   */\n  private _continueUserSessionAfterPartEnd(partEndTs: number): void {\n    if (!this._state) {\n      this._clearMaxDurationTimer();\n      return;\n    }\n\n    // If the state row was present at part start but is gone now (user\n    // Wiped site data, quota eviction, sibling tab cleared), don't\n    // Resurrect it from memory. Drop in-memory state so the next part\n    // Start creates a fresh user session; carry the just-ended id\n    // Forward so the next session can back-link to it.\n    // _hasStoredState gates this: if we never persisted in the first\n    // Place, the in-memory copy stays authoritative.\n    if (\n      this._hasStoredState &&\n      this._storage.getItem(MXL_USER_SESSION_STATE_KEY) === null\n    ) {\n      this._previousUserSessionId = this._state.userSessionId;\n      this._state = null;\n      this._clearMaxDurationTimer();\n      return;\n    }\n\n    this._state = {\n      ...this._state,\n      inactivityDeadlineTs:\n        partEndTs + this._state.inactivityTimeoutSeconds * 1000,\n    };\n    this._storeState();\n  }\n\n  /**\n   * Ends the active part as final and starts a fresh part for the next\n   * user session. State clearing for the engaged path is handled by\n   * endSessionPartInternal's isFinal branch. When no part is active\n   * (tab disengaged), the same state-clearing is performed inline so\n   * the next engagement creates a fresh user session rather than\n   * resuming the just-ended one.\n   */\n  private _rolloverUserSession(\n    userSessionEndReason: UserSessionEndReason,\n  ): void {\n    if (this._sessionPartSpan) {\n      this.endSessionPartInternal('user_session_ended', userSessionEndReason);\n      this.startSessionPartInternal('user_session_rollover');\n      return;\n    }\n\n    this._previousUserSessionId = this._state?.userSessionId ?? null;\n    this._state = null;\n    this._storage.removeItem(MXL_USER_SESSION_STATE_KEY);\n    this._clearMaxDurationTimer();\n  }\n\n  private _setupMaxDurationTimer(state: UserSessionState, now: number): void {\n    this._clearMaxDurationTimer();\n\n    const remaining = state.userSessionMaxEndTs - now;\n    if (remaining <= 0) {\n      return;\n    }\n\n    this._maxDurationTimeout = setTimeout(() => {\n      this._maxDurationTimeout = null;\n      this._rolloverUserSession('max_duration_reached');\n    }, remaining);\n  }\n\n  /**\n   * @internal Would be private but exposed for tests to simulate a page reload\n   */\n  public _clearMaxDurationTimer(): void {\n    if (this._maxDurationTimeout !== null) {\n      clearTimeout(this._maxDurationTimeout);\n      this._maxDurationTimeout = null;\n    }\n  }\n\n  /**\n   * Detaches browser-activity listeners and clears the part-inactivity\n   * timer. Intended for SDK teardown and tests; in production the manager\n   * lives for the page's lifetime.\n   */\n  public _shutdown(): void {\n    if (this._isShutdown) {\n      return;\n    }\n    this._isShutdown = true;\n    MXLUserSessionManager._testInstances.delete(this);\n    this._onActivityThrottled.cancel();\n    removeActivityListeners({\n      activityEvents: this._activityEvents,\n      onActivity: this._onActivityThrottled,\n      onBlur: this._onBlur,\n      onFocus: this._onFocus,\n      onPageHide: this._onPageHide,\n      onPageShow: this._onPageShow,\n      onVisibilityChange: this._onVisibilityChange,\n      target: this._target,\n      visibilityDoc: this._visibilityDoc,\n    });\n    this._clearSessionPartInactivityTimer();\n    this._clearMaxDurationTimer();\n  }\n\n  private readonly _onActivity = (): void => {\n    try {\n      if (!isTabEngaged(this._visibilityDoc)) {\n        return;\n      }\n      if (this._activeSessionPartId === null) {\n        this.startSessionPartInternal('web_activity');\n        return;\n      }\n      this._startSessionPartInactivityTimer();\n    } catch (error) {\n      this._diag.warn('Error handling activity event', error);\n    }\n  };\n\n  // Tab visibility flipped (switch tabs, minimize, OS app switch). Drives\n  // The engagement transition off the current visibilityState/hasFocus pair.\n  private readonly _onVisibilityChange = (): void => {\n    this._handleEngagementTransition('visibilitychange');\n  };\n\n  // Window focus arrived (alt-tab back, clicked into the document). hasFocus\n  // Is now true; engagement transition resolves whether to start a part.\n  private readonly _onFocus = (): void => {\n    this._handleEngagementTransition('focus');\n  };\n\n  // Window focus lost (alt-tab away, clicked into DevTools or another window).\n  // HasFocus is now false; engagement transition ends the active part.\n  private readonly _onBlur = (): void => {\n    this._handleEngagementTransition('blur');\n  };\n\n  // Initial page load OR BFCache restore. event.persisted only affects the\n  // Debug source string; routing is via _handleEngagementTransition, which\n  // Keys off engagement state and whether a part is currently active.\n  private readonly _onPageShow = (event: PageTransitionEvent): void => {\n    this._handleEngagementTransition(\n      event.persisted ? 'pageshow-bfcache' : 'pageshow-initial',\n    );\n  };\n\n  // Navigation away (hard nav, tab close) OR BFCache freeze. Both signal the\n  // Page is about to stop running, so we always end the active part. Ending\n  // The part flushes its span (and the spans batched against it in\n  // MXLSessionPartBatchedSpanProcessor) through the export pipeline while\n  // The page can still issue a keepalive fetch. On BFCache restore, pageshow\n  // Will start a fresh part.\n  private readonly _onPageHide = (event: PageTransitionEvent): void => {\n    try {\n      if (this._activeSessionPartId === null) {\n        return;\n      }\n      const reason: SessionPartEndReason = event.persisted\n        ? 'web_background'\n        : 'web_hard_navigation';\n      this._diag.debug(\n        `page hiding (persisted=${event.persisted}); ending current part as ${reason}`,\n      );\n      this.endSessionPartInternal(reason);\n    } catch (error) {\n      this._diag.error(\n        `Error ending session part on pagehide (persisted=${event.persisted})`,\n        error,\n      );\n    }\n  };\n\n  private _handleEngagementTransition(source: string): void {\n    try {\n      const engaged = isTabEngaged(this._visibilityDoc);\n      const active = this._activeSessionPartId !== null;\n      if (!engaged && active) {\n        this._diag.debug(`tab disengaged via ${source}; ending current part`);\n        this.endSessionPartInternal('web_background');\n        return;\n      }\n      if (engaged && !active) {\n        this._diag.debug(`tab engaged via ${source}; starting new part`);\n        this.startSessionPartInternal('web_foreground');\n        return;\n      }\n      if (engaged && active) {\n        // Redundant engagement event while a part is already active (browser\n        // Quirk: an extra focus/visibility fire that isn't a real transition).\n        // Re-arm the inactivity timer since the event still implies presence.\n        this._startSessionPartInactivityTimer();\n      }\n    } catch (error) {\n      this._diag.warn('Error handling engagement change', error);\n    }\n  }\n\n  private readonly _onSessionPartInactivity = (): void => {\n    this._sessionPartInactivityTimer = null;\n    try {\n      if (this._activeSessionPartId === null) {\n        return;\n      }\n      this._diag.debug(\n        'inactivity timer fired; ending current part and user session',\n      );\n      this.endSessionPartInternal('inactivity', 'inactivity');\n    } catch (error) {\n      this._diag.warn('Error handling inactivity timer', error);\n    }\n  };\n\n  private _startSessionPartInactivityTimer(): void {\n    this._clearSessionPartInactivityTimer();\n    this._sessionPartInactivityTimer = setTimeout(\n      this._onSessionPartInactivity,\n      this._inactivityTimeoutSeconds * 1000,\n    );\n  }\n\n  private _clearSessionPartInactivityTimer(): void {\n    if (this._sessionPartInactivityTimer !== null) {\n      clearTimeout(this._sessionPartInactivityTimer);\n      this._sessionPartInactivityTimer = null;\n    }\n  }\n\n  private _addListener(list: (() => void)[], listener: () => void): () => void {\n    list.push(listener);\n    return () => {\n      const i = list.indexOf(listener);\n      if (i !== -1) {\n        list.splice(i, 1);\n      }\n    };\n  }\n\n  private _fireListeners(list: (() => void)[], kind: string): void {\n    for (const listener of list) {\n      try {\n        listener();\n      } catch (error) {\n        this._diag.warn(\n          `Error while executing session part ${kind} listener`,\n          error,\n        );\n      }\n    }\n  }\n\n  private _storeState(): boolean {\n    if (!this._state) {\n      return false;\n    }\n    const stored = this._storage.setItem(\n      MXL_USER_SESSION_STATE_KEY,\n      JSON.stringify(this._state),\n    );\n    if (stored) {\n      this._hasStoredState = true;\n    }\n    return stored;\n  }\n\n  private _removeFromPermanentProperties(bareKey: string): void {\n    if (!(bareKey in this._permanentProperties)) {\n      return;\n    }\n    const pruned = { ...this._permanentProperties };\n    delete pruned[bareKey];\n    this._permanentProperties = pruned;\n    storePermanentProperties(this._storage, pruned);\n  }\n\n  private _removeFromUserSessionProperties(bareKey: string): void {\n    if (!this._state || !(bareKey in this._state.userSessionProperties)) {\n      return;\n    }\n    const pruned = { ...this._state.userSessionProperties };\n    delete pruned[bareKey];\n    this._state = {\n      ...this._state,\n      userSessionProperties: pruned,\n    };\n    this._storeState();\n  }\n}\n"],"mappings":"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"}

package/dist/managers/MXLUserSessionManager/MXLUserSessionManager.d.cts

@@ -0,0 +1,142 @@
+import { ExtendedSpan } from "../../api-traces/api/TraceAPI/types.cjs";
+import { PropertyOptions, SessionPartEndReason, SessionPartStartReason, UserSessionEndReason } from "../../api-sessions/manager/types.cjs";
+import { MXLUserSessionManagerArgs, UserSessionAttributes, UserSessionManagerInternal } from "./types.cjs";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/managers/MXLUserSessionManager/MXLUserSessionManager.d.ts
+/**
+ * Parts are engagement-gated (visible AND focused), so only one part can
+ * be active at a time. That mutex lets us treat storage as a
+ * plain shared row read on engagement and written on changes.
+ */
+declare class MXLUserSessionManager implements UserSessionManagerInternal {
+  private static readonly _testInstances;
+  /** @internal Test-only helper to tear down leaked managers between tests. */
+  static shutdownAllTestInstances(): void;
+  private _state;
+  private _previousUserSessionId;
+  private readonly _maxUserSessionDurationSeconds;
+  private readonly _inactivityTimeoutSeconds;
+  private _maxDurationTimeout;
+  private _isShutdown;
+  private _permanentProperties;
+  private _hasStoredState;
+  private _activeSessionPartId;
+  private _currentSessionPartNumber;
+  private _sessionPartSpan;
+  private _activeSessionPartCounts;
+  private _coldStart;
+  private _nextSessionPartCounts;
+  private _sdkStartupDuration;
+  private readonly _sessionPartStartedListeners;
+  private readonly _sessionPartEndedListeners;
+  private _tracer;
+  private readonly _diag;
+  private readonly _perf;
+  private readonly _storage;
+  private readonly _visibilityDoc;
+  private readonly _limitManager;
+  private readonly _target;
+  private readonly _activityEvents;
+  private readonly _onActivityThrottled;
+  private _sessionPartInactivityTimer;
+  private readonly _tab;
+  private readonly _navigationSource;
+  private readonly _referrerScrubbedUrl?;
+  constructor({
+    config,
+    diag: diagParam,
+    perf,
+    visibilityDoc,
+    storage,
+    limitManager,
+    target,
+    activityThrottleMs,
+    activityEvents,
+    tabStorage,
+    referrer,
+    navigationPerformance
+  }: MXLUserSessionManagerArgs);
+  setTracerProvider(tracerProvider: TracerProvider): void;
+  recordSDKStartupDuration(duration: number): void;
+  getUserSessionId(): string | null;
+  getPreviousUserSessionId(): string | null;
+  getUserSessionStartTime(): number | null;
+  getUserSessionAttributes(): UserSessionAttributes | null;
+  endUserSession(): void;
+  getSessionPartId(): string | null;
+  getSessionPartSpan(): ExtendedSpan | null;
+  startSessionPartInternal(reason: SessionPartStartReason): void;
+  endSessionPartInternal(reason: SessionPartEndReason, userSessionEndReason?: UserSessionEndReason | null): void;
+  addBreadcrumb(name: string): void;
+  addProperty(propertyKey: string, value: string, options?: PropertyOptions): void;
+  removeProperty(propertyKey: string): void;
+  /**
+   * Bare-keyed view of properties for the active part. User-session-scoped
+   * entries shadow permanent ones, matching the cross-scope flip rule
+   * enforced in `addProperty`. Callers apply the wire-format prefix at
+   * stamp time.
+   */
+  getSessionPartProperties(): Record<string, string>;
+  incrSessionPartCountForKey(key: string): void;
+  incrNextSessionPartCountForKey(key: string): void;
+  addSessionPartStartedListener(listener: () => void): () => void;
+  addSessionPartEndedListener(listener: () => void): () => void;
+  /**
+   * Returns the persisted user-session state, rotating to a fresh one if
+   * the persisted row is missing or expired. Arms the max-duration timer
+   * when needed. The caller is responsible for assigning the result to
+   * `_state` and for persisting (the helper does not write to storage).
+   */
+  private _loadOrCreateUserSessionState;
+  /**
+   * Bumps the part counter and arms the max-duration timer. Relies on
+   * `_loadOrCreateUserSessionState` to provide a non-null, non-expired state,
+   * so `getUserSessionAttributes()` is guaranteed non-null after this.
+   */
+  private _beginUserSessionForPartStart;
+  /**
+   * Records the inactivity deadline on the user-session row so the next
+   * part start can detect lazy expiry. The max-duration timer stays valid
+   * because userSessionMaxEndTs doesn't change between parts.
+   */
+  private _continueUserSessionAfterPartEnd;
+  /**
+   * Ends the active part as final and starts a fresh part for the next
+   * user session. State clearing for the engaged path is handled by
+   * endSessionPartInternal's isFinal branch. When no part is active
+   * (tab disengaged), the same state-clearing is performed inline so
+   * the next engagement creates a fresh user session rather than
+   * resuming the just-ended one.
+   */
+  private _rolloverUserSession;
+  private _setupMaxDurationTimer;
+  /**
+   * @internal Would be private but exposed for tests to simulate a page reload
+   */
+  _clearMaxDurationTimer(): void;
+  /**
+   * Detaches browser-activity listeners and clears the part-inactivity
+   * timer. Intended for SDK teardown and tests; in production the manager
+   * lives for the page's lifetime.
+   */
+  _shutdown(): void;
+  private readonly _onActivity;
+  private readonly _onVisibilityChange;
+  private readonly _onFocus;
+  private readonly _onBlur;
+  private readonly _onPageShow;
+  private readonly _onPageHide;
+  private _handleEngagementTransition;
+  private readonly _onSessionPartInactivity;
+  private _startSessionPartInactivityTimer;
+  private _clearSessionPartInactivityTimer;
+  private _addListener;
+  private _fireListeners;
+  private _storeState;
+  private _removeFromPermanentProperties;
+  private _removeFromUserSessionProperties;
+}
+//#endregion
+export { MXLUserSessionManager };
+//# sourceMappingURL=MXLUserSessionManager.d.cts.map

package/dist/managers/MXLUserSessionManager/MXLUserSessionManager.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MXLUserSessionManager.d.cts","names":[],"sources":["../../../src/managers/MXLUserSessionManager/MXLUserSessionManager.ts"],"mappings":";;;;;;;;AAgEA;;;cAAa,qBAAA,YAAiC,0BAAA;EAAA,wBACpB,cAAA;EAwDtB;EAAA,OArDY,wBAAA,CAAA;EAAA,QAON,MAAA;EAAA,QACA,sBAAA;EAAA,iBACS,8BAAA;EAAA,iBACA,yBAAA;EAAA,QACT,mBAAA;EAAA,QACA,WAAA;EAAA,QAEA,oBAAA;EAAA,QAIA,eAAA;EAAA,QAEA,oBAAA;EAAA,QAGA,yBAAA;EAAA,QACA,gBAAA;EAAA,QACA,wBAAA;EAAA,QAGA,UAAA;EAAA,QACA,sBAAA;EAAA,QACA,mBAAA;EAAA,iBACS,4BAAA;EAAA,iBACA,0BAAA;EAAA,QACT,OAAA;EAAA,iBAES,KAAA;EAAA,iBACA,KAAA;EAAA,iBACA,QAAA;EAAA,iBACA,cAAA;EAAA,iBACA,aAAA;EAAA,iBACA,OAAA;EAAA,iBACA,eAAA;EAAA,iBACA,oBAAA;EAAA,QAGT,2BAAA;EAAA,iBACS,IAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,oBAAA;;IAGf,MAAA;IACA,IAAA,EAAM,SAAA;IACN,IAAA;IACA,aAAA;IACA,OAAA;IACA,YAAA;IACA,MAAA;IACA,kBAAA;IACA,cAAA;IACA,UAAA;IACA,QAAA;IACA;EAAA,GAGC,yBAAA;EA6DI,iBAAA,CAAkB,cAAA,EAAgB,cAAA;EA6BlC,wBAAA,CAAyB,QAAA;EAIzB,gBAAA,CAAA;EAIA,wBAAA,CAAA;EAMA,uBAAA,CAAA;EAIA,wBAAA,CAAA,GAA4B,qBAAA;EAqB5B,cAAA,CAAA;EAyBA,gBAAA,CAAA;EAIA,kBAAA,CAAA,GAAsB,YAAA;EAItB,wBAAA,CAAyB,MAAA,EAAQ,sBAAA;EAmEjC,sBAAA,CACL,MAAA,EAAQ,oBAAA,EACR,oBAAA,GAAuB,oBAAA;EA6ElB,aAAA,CAAc,IAAA;EAsBd,WAAA,CACL,WAAA,UACA,KAAA,UACA,OAAA,GAAU,eAAA;EAuDL,cAAA,CAAe,WAAA;EA9ZL;;;;;;EAgbV,wBAAA,CAAA,GAA4B,MAAA;EAO5B,0BAAA,CAA2B,GAAA;EAW3B,8BAAA,CAA+B,GAAA;EAK/B,6BAAA,CAA8B,QAAA;EAI9B,2BAAA,CAA4B,QAAA;EA9bjC;;;;;;EAAA,QAwcM,6BAAA;EArcN;;;;;EAAA,QA4eM,6BAAA;EAzeN;;;;;EAAA,QAkgBM,gCAAA;EA/fN;;;;;;;;EAAA,QAsiBM,oBAAA;EAAA,QAeA,sBAAA;EA/cD;;;EAgeA,sBAAA,CAAA;EAjcA;;;;;EA6cA,SAAA,CAAA;EAAA,iBAsBU,WAAA;EAAA,iBAiBA,mBAAA;EAAA,iBAMA,QAAA;EAAA,iBAMA,OAAA;EAAA,iBAOA,WAAA;EAAA,iBAYA,WAAA;EAAA,QAoBT,2BAAA;EAAA,iBAyBS,wBAAA;EAAA,QAeT,gCAAA;EAAA,QAQA,gCAAA;EAAA,QAOA,YAAA;EAAA,QAUA,cAAA;EAAA,QAaA,WAAA;EAAA,QAcA,8BAAA;EAAA,QAUA,gCAAA;AAAA"}

package/dist/managers/MXLUserSessionManager/MXLUserSessionManager.d.ts

@@ -0,0 +1,142 @@
+import { ExtendedSpan } from "../../api-traces/api/TraceAPI/types.js";
+import { PropertyOptions, SessionPartEndReason, SessionPartStartReason, UserSessionEndReason } from "../../api-sessions/manager/types.js";
+import { MXLUserSessionManagerArgs, UserSessionAttributes, UserSessionManagerInternal } from "./types.js";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/managers/MXLUserSessionManager/MXLUserSessionManager.d.ts
+/**
+ * Parts are engagement-gated (visible AND focused), so only one part can
+ * be active at a time. That mutex lets us treat storage as a
+ * plain shared row read on engagement and written on changes.
+ */
+declare class MXLUserSessionManager implements UserSessionManagerInternal {
+  private static readonly _testInstances;
+  /** @internal Test-only helper to tear down leaked managers between tests. */
+  static shutdownAllTestInstances(): void;
+  private _state;
+  private _previousUserSessionId;
+  private readonly _maxUserSessionDurationSeconds;
+  private readonly _inactivityTimeoutSeconds;
+  private _maxDurationTimeout;
+  private _isShutdown;
+  private _permanentProperties;
+  private _hasStoredState;
+  private _activeSessionPartId;
+  private _currentSessionPartNumber;
+  private _sessionPartSpan;
+  private _activeSessionPartCounts;
+  private _coldStart;
+  private _nextSessionPartCounts;
+  private _sdkStartupDuration;
+  private readonly _sessionPartStartedListeners;
+  private readonly _sessionPartEndedListeners;
+  private _tracer;
+  private readonly _diag;
+  private readonly _perf;
+  private readonly _storage;
+  private readonly _visibilityDoc;
+  private readonly _limitManager;
+  private readonly _target;
+  private readonly _activityEvents;
+  private readonly _onActivityThrottled;
+  private _sessionPartInactivityTimer;
+  private readonly _tab;
+  private readonly _navigationSource;
+  private readonly _referrerScrubbedUrl?;
+  constructor({
+    config,
+    diag: diagParam,
+    perf,
+    visibilityDoc,
+    storage,
+    limitManager,
+    target,
+    activityThrottleMs,
+    activityEvents,
+    tabStorage,
+    referrer,
+    navigationPerformance
+  }: MXLUserSessionManagerArgs);
+  setTracerProvider(tracerProvider: TracerProvider): void;
+  recordSDKStartupDuration(duration: number): void;
+  getUserSessionId(): string | null;
+  getPreviousUserSessionId(): string | null;
+  getUserSessionStartTime(): number | null;
+  getUserSessionAttributes(): UserSessionAttributes | null;
+  endUserSession(): void;
+  getSessionPartId(): string | null;
+  getSessionPartSpan(): ExtendedSpan | null;
+  startSessionPartInternal(reason: SessionPartStartReason): void;
+  endSessionPartInternal(reason: SessionPartEndReason, userSessionEndReason?: UserSessionEndReason | null): void;
+  addBreadcrumb(name: string): void;
+  addProperty(propertyKey: string, value: string, options?: PropertyOptions): void;
+  removeProperty(propertyKey: string): void;
+  /**
+   * Bare-keyed view of properties for the active part. User-session-scoped
+   * entries shadow permanent ones, matching the cross-scope flip rule
+   * enforced in `addProperty`. Callers apply the wire-format prefix at
+   * stamp time.
+   */
+  getSessionPartProperties(): Record<string, string>;
+  incrSessionPartCountForKey(key: string): void;
+  incrNextSessionPartCountForKey(key: string): void;
+  addSessionPartStartedListener(listener: () => void): () => void;
+  addSessionPartEndedListener(listener: () => void): () => void;
+  /**
+   * Returns the persisted user-session state, rotating to a fresh one if
+   * the persisted row is missing or expired. Arms the max-duration timer
+   * when needed. The caller is responsible for assigning the result to
+   * `_state` and for persisting (the helper does not write to storage).
+   */
+  private _loadOrCreateUserSessionState;
+  /**
+   * Bumps the part counter and arms the max-duration timer. Relies on
+   * `_loadOrCreateUserSessionState` to provide a non-null, non-expired state,
+   * so `getUserSessionAttributes()` is guaranteed non-null after this.
+   */
+  private _beginUserSessionForPartStart;
+  /**
+   * Records the inactivity deadline on the user-session row so the next
+   * part start can detect lazy expiry. The max-duration timer stays valid
+   * because userSessionMaxEndTs doesn't change between parts.
+   */
+  private _continueUserSessionAfterPartEnd;
+  /**
+   * Ends the active part as final and starts a fresh part for the next
+   * user session. State clearing for the engaged path is handled by
+   * endSessionPartInternal's isFinal branch. When no part is active
+   * (tab disengaged), the same state-clearing is performed inline so
+   * the next engagement creates a fresh user session rather than
+   * resuming the just-ended one.
+   */
+  private _rolloverUserSession;
+  private _setupMaxDurationTimer;
+  /**
+   * @internal Would be private but exposed for tests to simulate a page reload
+   */
+  _clearMaxDurationTimer(): void;
+  /**
+   * Detaches browser-activity listeners and clears the part-inactivity
+   * timer. Intended for SDK teardown and tests; in production the manager
+   * lives for the page's lifetime.
+   */
+  _shutdown(): void;
+  private readonly _onActivity;
+  private readonly _onVisibilityChange;
+  private readonly _onFocus;
+  private readonly _onBlur;
+  private readonly _onPageShow;
+  private readonly _onPageHide;
+  private _handleEngagementTransition;
+  private readonly _onSessionPartInactivity;
+  private _startSessionPartInactivityTimer;
+  private _clearSessionPartInactivityTimer;
+  private _addListener;
+  private _fireListeners;
+  private _storeState;
+  private _removeFromPermanentProperties;
+  private _removeFromUserSessionProperties;
+}
+//#endregion
+export { MXLUserSessionManager };
+//# sourceMappingURL=MXLUserSessionManager.d.ts.map

package/dist/managers/MXLUserSessionManager/MXLUserSessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MXLUserSessionManager.d.ts","names":[],"sources":["../../../src/managers/MXLUserSessionManager/MXLUserSessionManager.ts"],"mappings":";;;;;;;;AAgEA;;;cAAa,qBAAA,YAAiC,0BAAA;EAAA,wBACpB,cAAA;EAwDtB;EAAA,OArDY,wBAAA,CAAA;EAAA,QAON,MAAA;EAAA,QACA,sBAAA;EAAA,iBACS,8BAAA;EAAA,iBACA,yBAAA;EAAA,QACT,mBAAA;EAAA,QACA,WAAA;EAAA,QAEA,oBAAA;EAAA,QAIA,eAAA;EAAA,QAEA,oBAAA;EAAA,QAGA,yBAAA;EAAA,QACA,gBAAA;EAAA,QACA,wBAAA;EAAA,QAGA,UAAA;EAAA,QACA,sBAAA;EAAA,QACA,mBAAA;EAAA,iBACS,4BAAA;EAAA,iBACA,0BAAA;EAAA,QACT,OAAA;EAAA,iBAES,KAAA;EAAA,iBACA,KAAA;EAAA,iBACA,QAAA;EAAA,iBACA,cAAA;EAAA,iBACA,aAAA;EAAA,iBACA,OAAA;EAAA,iBACA,eAAA;EAAA,iBACA,oBAAA;EAAA,QAGT,2BAAA;EAAA,iBACS,IAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,oBAAA;;IAGf,MAAA;IACA,IAAA,EAAM,SAAA;IACN,IAAA;IACA,aAAA;IACA,OAAA;IACA,YAAA;IACA,MAAA;IACA,kBAAA;IACA,cAAA;IACA,UAAA;IACA,QAAA;IACA;EAAA,GAGC,yBAAA;EA6DI,iBAAA,CAAkB,cAAA,EAAgB,cAAA;EA6BlC,wBAAA,CAAyB,QAAA;EAIzB,gBAAA,CAAA;EAIA,wBAAA,CAAA;EAMA,uBAAA,CAAA;EAIA,wBAAA,CAAA,GAA4B,qBAAA;EAqB5B,cAAA,CAAA;EAyBA,gBAAA,CAAA;EAIA,kBAAA,CAAA,GAAsB,YAAA;EAItB,wBAAA,CAAyB,MAAA,EAAQ,sBAAA;EAmEjC,sBAAA,CACL,MAAA,EAAQ,oBAAA,EACR,oBAAA,GAAuB,oBAAA;EA6ElB,aAAA,CAAc,IAAA;EAsBd,WAAA,CACL,WAAA,UACA,KAAA,UACA,OAAA,GAAU,eAAA;EAuDL,cAAA,CAAe,WAAA;EA9ZL;;;;;;EAgbV,wBAAA,CAAA,GAA4B,MAAA;EAO5B,0BAAA,CAA2B,GAAA;EAW3B,8BAAA,CAA+B,GAAA;EAK/B,6BAAA,CAA8B,QAAA;EAI9B,2BAAA,CAA4B,QAAA;EA9bjC;;;;;;EAAA,QAwcM,6BAAA;EArcN;;;;;EAAA,QA4eM,6BAAA;EAzeN;;;;;EAAA,QAkgBM,gCAAA;EA/fN;;;;;;;;EAAA,QAsiBM,oBAAA;EAAA,QAeA,sBAAA;EA/cD;;;EAgeA,sBAAA,CAAA;EAjcA;;;;;EA6cA,SAAA,CAAA;EAAA,iBAsBU,WAAA;EAAA,iBAiBA,mBAAA;EAAA,iBAMA,QAAA;EAAA,iBAMA,OAAA;EAAA,iBAOA,WAAA;EAAA,iBAYA,WAAA;EAAA,QAoBT,2BAAA;EAAA,iBAyBS,wBAAA;EAAA,QAeT,gCAAA;EAAA,QAQA,gCAAA;EAAA,QAOA,YAAA;EAAA,QAUA,cAAA;EAAA,QAaA,WAAA;EAAA,QAcA,8BAAA;EAAA,QAUA,gCAAA;AAAA"}