@kubesense/kubesense-browser-core 1.0.0

package/src/domain/trackingConsent.ts

@@ -0,0 +1,34 @@
+import { Observable } from '../tools/observable'
+
+export const TrackingConsent = {
+  GRANTED: 'granted',
+  NOT_GRANTED: 'not-granted',
+} as const
+export type TrackingConsent = (typeof TrackingConsent)[keyof typeof TrackingConsent]
+
+export interface TrackingConsentState {
+  tryToInit: (trackingConsent: TrackingConsent) => void
+  update: (trackingConsent: TrackingConsent) => void
+  isGranted: () => boolean
+  observable: Observable<void>
+}
+
+export function createTrackingConsentState(currentConsent?: TrackingConsent): TrackingConsentState {
+  const observable = new Observable<void>()
+
+  return {
+    tryToInit(trackingConsent: TrackingConsent) {
+      if (!currentConsent) {
+        currentConsent = trackingConsent
+      }
+    },
+    update(trackingConsent: TrackingConsent) {
+      currentConsent = trackingConsent
+      observable.notify()
+    },
+    isGranted() {
+      return currentConsent === TrackingConsent.GRANTED
+    },
+    observable,
+  }
+}

package/src/domain/userAgentData/index.ts

@@ -0,0 +1 @@
+export * from './userAgentData'

package/src/domain/userAgentData/userAgentData.ts

@@ -0,0 +1,163 @@
+import { globalObject } from '../../tools/globalObject'
+
+export interface UserAgentBrowser {
+  name: string
+  version: string
+}
+
+export interface UserAgentOS {
+  name: string
+  version: string
+  version_major: string
+}
+
+export interface UserAgentDevice {
+  type?: 'mobile' | 'desktop' | 'tablet' | 'tv' | 'gaming_console' | 'bot' | 'other'
+  model?: string
+  brand?: string
+  architecture?: string
+}
+
+export interface UserAgentContext {
+  browser?: UserAgentBrowser
+  os?: UserAgentOS
+  device?: UserAgentDevice
+}
+
+interface UADataBrand {
+  brand: string
+  version: string
+}
+
+interface NavigatorUAData {
+  readonly brands: UADataBrand[]
+  readonly mobile: boolean
+  readonly platform: string
+  getHighEntropyValues(hints: string[]): Promise<{
+    architecture?: string
+    bitness?: string
+    brands?: UADataBrand[]
+    fullVersionList?: UADataBrand[]
+    mobile?: boolean
+    model?: string
+    platform?: string
+    platformVersion?: string
+    wow64?: boolean
+  }>
+}
+
+interface NavigatorWithUAData extends Navigator {
+  userAgentData?: NavigatorUAData
+}
+
+// Chromium ships its brand list with intentionally-shuffled "Not-A.Brand" /
+// "Not(A:Brand" entries to discourage UA sniffing. Pick the most-specific real
+// brand: Edge > Chrome > Chromium > anything else.
+const BRAND_PRIORITY: Record<string, number> = {
+  'Microsoft Edge': 1,
+  'Google Chrome': 2,
+  Chromium: 3,
+  Opera: 4,
+  Brave: 5,
+}
+
+function pickBrand(brands: UADataBrand[] | undefined): UADataBrand | undefined {
+  if (!brands || brands.length === 0) {
+    return undefined
+  }
+  let best: UADataBrand | undefined
+  let bestPriority = Number.MAX_SAFE_INTEGER
+  for (const entry of brands) {
+    if (!entry.brand || entry.brand.indexOf('Not') === 0) {
+      continue
+    }
+    const priority = BRAND_PRIORITY[entry.brand] ?? 99
+    if (priority < bestPriority) {
+      best = entry
+      bestPriority = priority
+    }
+  }
+  return best ?? brands.find((b) => b.brand && b.brand.indexOf('Not') !== 0)
+}
+
+function majorVersion(version: string): string {
+  const dot = version.indexOf('.')
+  return dot >= 0 ? version.slice(0, dot) : version
+}
+
+function getUAData(): NavigatorUAData | undefined {
+  const nav = globalObject.navigator as NavigatorWithUAData | undefined
+  return nav?.userAgentData
+}
+
+// Sync values available immediately on first paint: brand + major version
+// from low-entropy hints. We deliberately do NOT emit os/device here — only
+// the platform *name* is available synchronously, not the version, and the
+// server's setOperatingSystem/setDevice overwrites unconditionally, so
+// shipping empty version strings would clobber the server-side UA fallback.
+// Browser brand + major version, by contrast, is reliable from sync hints.
+// Returns undefined on non-Chromium so the server's UA parser handles
+// Safari/Firefox — their classic UA isn't frozen.
+export function getSyncUserAgentContext(): UserAgentContext | undefined {
+  const uaData = getUAData()
+  if (!uaData) {
+    return undefined
+  }
+  const brand = pickBrand(uaData.brands)
+  if (!brand) {
+    return undefined
+  }
+  return { browser: { name: brand.brand, version: brand.version } }
+}
+
+// Async high-entropy values: full browser version, real OS version (recovers
+// the value the classic UA freezes — macOS 14.x.y instead of 10.15.7, Windows
+// 13.x build instead of 10.0), model on mobile, CPU architecture.
+export function resolveHighEntropyUserAgentContext(): Promise<UserAgentContext | undefined> {
+  const uaData = getUAData()
+  if (!uaData || typeof uaData.getHighEntropyValues !== 'function') {
+    return Promise.resolve(undefined)
+  }
+
+  return uaData
+    .getHighEntropyValues(['fullVersionList', 'platformVersion', 'model', 'architecture', 'bitness'])
+    .then((values) => {
+      const ctx: UserAgentContext = {}
+
+      const fullBrand = pickBrand(values.fullVersionList) ?? pickBrand(uaData.brands)
+      if (fullBrand) {
+        ctx.browser = { name: fullBrand.brand, version: fullBrand.version }
+      }
+
+      // Only emit os when we have a real version — empty strings would
+      // overwrite the server-side UA fallback (setOperatingSystem is an
+      // unconditional assign). platformVersion can be blank when the page
+      // sets Permissions-Policy: ch-ua-platform-version=() or in some
+      // privacy-hardened browsers (Brave strict mode).
+      const platformVersion = values.platformVersion ?? ''
+      const platformName = uaData.platform || values.platform || ''
+      if (platformVersion && platformName) {
+        ctx.os = {
+          name: platformName,
+          version: platformVersion,
+          version_major: majorVersion(platformVersion),
+        }
+      }
+
+      // Same reasoning for device — only emit if we have a meaningful model
+      // or architecture; otherwise the server-side device_name/brand
+      // fallback ("Mac", "Apple", "Windows", …) survives.
+      const model = values.model || ''
+      const architecture = values.architecture || ''
+      if (model || architecture || uaData.mobile) {
+        ctx.device = {
+          type: uaData.mobile ? 'mobile' : 'desktop',
+          model: model || undefined,
+          architecture: architecture || undefined,
+        }
+      }
+
+      return ctx
+    })
+    .catch(() => undefined)
+}

package/src/index.ts

@@ -0,0 +1,169 @@
+export type { Configuration, InitConfiguration, EndpointBuilder, ProxyFn } from './domain/configuration'
+export {
+  validateAndBuildConfiguration,
+  DefaultPrivacyLevel,
+  TraceContextInjection,
+  serializeConfiguration,
+  isSampleRate,
+  buildEndpointHost,
+  INTAKE_URL_PARAMETERS,
+  INTAKE_SITE_PROD,
+  INTAKE_SITE_STAGING,
+  isIntakeUrl,
+} from './domain/configuration'
+export * from './domain/intakeSites'
+export type { TrackingConsentState } from './domain/trackingConsent'
+export { TrackingConsent, createTrackingConsentState } from './domain/trackingConsent'
+export {
+  isExperimentalFeatureEnabled,
+  addExperimentalFeatures,
+  resetExperimentalFeatures,
+  getExperimentalFeatures,
+  initFeatureFlags,
+  ExperimentalFeature,
+} from './tools/experimentalFeatures'
+export { trackRuntimeError } from './domain/error/trackRuntimeError'
+export type { StackTrace } from './tools/stackTrace/computeStackTrace'
+export { computeStackTrace } from './tools/stackTrace/computeStackTrace'
+export type { PublicApi } from './boot/init'
+export { defineGlobal, makePublicApi } from './boot/init'
+export { displayAlreadyInitializedError } from './boot/displayAlreadyInitializedError'
+export { initReportObservable, RawReportType } from './domain/report/reportObservable'
+export type {
+  Telemetry,
+  RawTelemetryEvent,
+  RawTelemetryConfiguration,
+  TelemetryEvent,
+  TelemetryErrorEvent,
+  TelemetryDebugEvent,
+  TelemetryConfigurationEvent,
+  TelemetryUsageEvent,
+  RawTelemetryUsage,
+  RawTelemetryUsageFeature,
+} from './domain/telemetry'
+export {
+  startTelemetry,
+  addTelemetryDebug,
+  addTelemetryError,
+  resetTelemetry,
+  TelemetryService,
+  TelemetryMetrics,
+  addTelemetryConfiguration,
+  addTelemetryUsage,
+  addTelemetryMetrics,
+} from './domain/telemetry'
+export { monitored, monitor, callMonitored, setDebugMode, monitorError } from './tools/monitor'
+export type { Subscription } from './tools/observable'
+export { Observable, BufferedObservable } from './tools/observable'
+export type { SessionManager } from './domain/session/sessionManager'
+export { startSessionManager, stopSessionManager } from './domain/session/sessionManager'
+export {
+  SESSION_TIME_OUT_DELAY, // Exposed for tests
+  SESSION_NOT_TRACKED,
+  SessionPersistence,
+} from './domain/session/sessionConstants'
+export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, FlushEvent, FlushReason } from './transport'
+export {
+  createHttpRequest,
+  canUseEventBridge,
+  getEventBridge,
+  bridgeSupports,
+  BridgeCapability,
+  createBatch,
+  createFlushController,
+  FLUSH_DURATION_LIMIT,
+} from './transport'
+export * from './tools/display'
+export type { Encoder, EncoderResult } from './tools/encoder'
+export { createIdentityEncoder } from './tools/encoder'
+export * from './tools/utils/urlPolyfill'
+export * from './tools/utils/timeUtils'
+export * from './tools/utils/arrayUtils'
+export * from './tools/serialisation/sanitize'
+export * from './tools/globalObject'
+export { AbstractLifeCycle } from './tools/abstractLifeCycle'
+export * from './domain/eventRateLimiter/createEventRateLimiter'
+export * from './tools/utils/browserDetection'
+export { sendToExtension } from './tools/sendToExtension'
+export { runOnReadyState, asyncRunOnReadyState } from './browser/runOnReadyState'
+export { getZoneJsOriginalValue } from './tools/getZoneJsOriginalValue'
+export type { InstrumentedMethodCall } from './tools/instrumentMethod'
+export { instrumentMethod, instrumentSetter } from './tools/instrumentMethod'
+export {
+  computeRawError,
+  getFileFromStackTraceString,
+  isError,
+  NO_ERROR_STACK_PRESENT_MESSAGE,
+} from './domain/error/error'
+export { NonErrorPrefix } from './domain/error/error.types'
+export type { Context, ContextArray, ContextValue } from './tools/serialisation/context'
+export {
+  areCookiesAuthorized,
+  getCookie,
+  getInitCookie,
+  setCookie,
+  deleteCookie,
+  resetInitCookies,
+} from './browser/cookie'
+export type { CookieStore, WeakRef, WeakRefConstructor } from './browser/browser.types'
+export type { XhrCompleteContext, XhrStartContext } from './browser/xhrObservable'
+export { initXhrObservable } from './browser/xhrObservable'
+export type { FetchResolveContext, FetchStartContext, FetchContext } from './browser/fetchObservable'
+export { initFetchObservable, resetFetchObservable, ResponseBodyAction } from './browser/fetchObservable'
+export type { PageMayExitEvent } from './browser/pageMayExitObservable'
+export { createPageMayExitObservable, PageExitReason, isPageExitReason } from './browser/pageMayExitObservable'
+export * from './browser/addEventListener'
+export { requestIdleCallback } from './tools/requestIdleCallback'
+export * from './tools/taskQueue'
+export * from './tools/timer'
+export type { ConsoleLog } from './domain/console/consoleObservable'
+export { initConsoleObservable, resetConsoleObservable } from './domain/console/consoleObservable'
+export type { BoundedBuffer } from './tools/boundedBuffer'
+export { createBoundedBuffer } from './tools/boundedBuffer'
+export { catchUserErrors } from './tools/catchUserErrors'
+export type { ContextManager } from './domain/context/contextManager'
+export { createContextManager } from './domain/context/contextManager'
+export { defineContextMethod, bufferContextCalls } from './domain/context/defineContextMethod'
+export { storeContextManager, removeStorageListeners } from './domain/context/storeContextManager'
+export { startAccountContext, buildAccountContextManager } from './domain/contexts/accountContext'
+export { startGlobalContext, buildGlobalContextManager } from './domain/contexts/globalContext'
+export { startUserContext, buildUserContextManager } from './domain/contexts/userContext'
+export type { User } from './domain/contexts/userContext'
+export type { Account } from './domain/contexts/accountContext'
+export type { RumInternalContext } from './domain/contexts/rumInternalContext.type'
+export { CustomerDataType, CustomerContextKey, ContextManagerMethod } from './domain/context/contextConstants'
+export type { ValueHistory, ValueHistoryEntry } from './tools/valueHistory'
+export { createValueHistory, CLEAR_OLD_VALUES_INTERVAL } from './tools/valueHistory'
+export { readBytesFromStream } from './tools/readBytesFromStream'
+export type { SessionState } from './domain/session/sessionState'
+export { STORAGE_POLL_DELAY } from './domain/session/sessionStore'
+export { SESSION_STORE_KEY } from './domain/session/storeStrategies/sessionStoreStrategy'
+export {
+  willSyntheticsInjectRum,
+  getSyntheticsTestId,
+  getSyntheticsResultId,
+  isSyntheticsTest,
+} from './domain/synthetics/syntheticsWorkerValues'
+export { checkContext } from './domain/context/contextUtils'
+export * from './domain/resourceUtils'
+export * from './domain/bufferedData'
+export * from './tools/utils/polyfills'
+export * from './tools/utils/timezone'
+export * from './tools/utils/numberUtils'
+export * from './tools/utils/byteUtils'
+export * from './tools/utils/objectUtils'
+export * from './tools/utils/functionUtils'
+export * from './tools/serialisation/jsonStringify'
+export * from './tools/mergeInto'
+export * from './tools/utils/stringUtils'
+export * from './tools/matchOption'
+export * from './tools/utils/responseUtils'
+export * from './tools/utils/typeUtils'
+export type { RawError, RawErrorCause, ErrorWithCause, Csp } from './domain/error/error.types'
+export { ErrorHandling, ErrorSource } from './domain/error/error.types'
+export * from './domain/deflate'
+export * from './domain/connectivity'
+export * from './domain/userAgentData'
+export * from './tools/stackTrace/handlingStack'
+export * from './tools/abstractHooks'
+export * from './domain/tags'

package/src/tools/abstractHooks.ts

@@ -0,0 +1,72 @@
+import { combine } from './mergeInto'
+
+export const enum HookNames {
+  Assemble,
+  AssembleTelemetry,
+}
+
+// This is a workaround for an issue occurring when the Browser SDK is included in a TypeScript
+// project configured with `isolatedModules: true`. Even if the const enum is declared in this
+// module, we cannot use it directly to define the EventMap interface keys (TS error: "Cannot access
+// ambient const enums when the '--isolatedModules' flag is provided.").
+export declare const HookNamesAsConst: {
+  ASSEMBLE: HookNames.Assemble
+  ASSEMBLE_TELEMETRY: HookNames.AssembleTelemetry
+}
+
+export type RecursivePartial<T> = {
+  [P in keyof T]?: T[P] extends Array<infer U>
+    ? Array<RecursivePartial<U>>
+    : T[P] extends object | undefined
+      ? RecursivePartial<T[P]>
+      : T[P]
+}
+
+// Discards the event from being sent
+export const DISCARDED = 'DISCARDED'
+// Skips from the assembly of the event
+export const SKIPPED = 'SKIPPED'
+
+export type DISCARDED = typeof DISCARDED
+export type SKIPPED = typeof SKIPPED
+
+export type AbstractHooks = ReturnType<typeof abstractHooks>
+
+export function abstractHooks<T extends { [K in HookNames]: (...args: any[]) => unknown }>() {
+  const callbacks: { [K in HookNames]?: Array<T[K]> } = {}
+
+  return {
+    register<K extends HookNames>(hookName: K, callback: T[K]) {
+      if (!callbacks[hookName]) {
+        callbacks[hookName] = []
+      }
+      callbacks[hookName]!.push(callback)
+      return {
+        unregister: () => {
+          callbacks[hookName] = callbacks[hookName]!.filter((cb) => cb !== callback)
+        },
+      }
+    },
+    triggerHook<K extends HookNames>(
+      hookName: K,
+      param: Parameters<T[K]>[0]
+    ): Exclude<ReturnType<T[K]>, SKIPPED> | DISCARDED | undefined {
+      const hookCallbacks = callbacks[hookName] || []
+      const results: any[] = []
+
+      for (const callback of hookCallbacks) {
+        const result = callback(param)
+        if (result === DISCARDED) {
+          return DISCARDED
+        }
+        if (result === SKIPPED) {
+          continue
+        }
+
+        results.push(result)
+      }
+
+      return combine(...(results as [any, any])) as Exclude<ReturnType<T[K]>, SKIPPED>
+    },
+  }
+}

package/src/tools/abstractLifeCycle.ts

@@ -0,0 +1,46 @@
+import type { Subscription } from './observable'
+
+/**
+ * Type helper to extract event types that have "void" data. This allows to call `notify` without a
+ * second argument. Ex:
+ *
+ * ```
+ * interface EventMap {
+ *   foo: void
+ * }
+ * const LifeCycle = AbstractLifeCycle<EventMap>
+ * new LifeCycle().notify('foo')
+ * ```
+ */
+type EventTypesWithoutData<EventMap> = {
+  [K in keyof EventMap]: EventMap[K] extends void ? K : never
+}[keyof EventMap]
+
+// eslint-disable-next-line no-restricted-syntax
+export class AbstractLifeCycle<EventMap> {
+  private callbacks: { [key in keyof EventMap]?: Array<(data: any) => void> } = {}
+
+  notify<EventType extends EventTypesWithoutData<EventMap>>(eventType: EventType): void
+  notify<EventType extends keyof EventMap>(eventType: EventType, data: EventMap[EventType]): void
+  notify(eventType: keyof EventMap, data?: unknown) {
+    const eventCallbacks = this.callbacks[eventType]
+    if (eventCallbacks) {
+      eventCallbacks.forEach((callback) => callback(data))
+    }
+  }
+
+  subscribe<EventType extends keyof EventMap>(
+    eventType: EventType,
+    callback: (data: EventMap[EventType]) => void
+  ): Subscription {
+    if (!this.callbacks[eventType]) {
+      this.callbacks[eventType] = []
+    }
+    this.callbacks[eventType]!.push(callback)
+    return {
+      unsubscribe: () => {
+        this.callbacks[eventType] = this.callbacks[eventType]!.filter((other) => callback !== other)
+      },
+    }
+  }
+}

package/src/tools/boundedBuffer.ts

@@ -0,0 +1,44 @@
+import { removeItem } from './utils/arrayUtils'
+
+const BUFFER_LIMIT = 500
+/**
+ * BoundedBuffer is a deprecated interface.
+ *
+ * @deprecated Use `BufferedObservable` instead.
+ */
+export interface BoundedBuffer<T = void> {
+  add: (callback: (arg: T) => void) => void
+  remove: (callback: (arg: T) => void) => void
+  drain: (arg: T) => void
+}
+
+/**
+ * createBoundedBuffer creates a BoundedBuffer.
+ *
+ * @deprecated Use `BufferedObservable` instead.
+ */
+export function createBoundedBuffer<T = void>(): BoundedBuffer<T> {
+  const buffer: Array<(arg: T) => void> = []
+
+  const add: BoundedBuffer<T>['add'] = (callback: (arg: T) => void) => {
+    const length = buffer.push(callback)
+    if (length > BUFFER_LIMIT) {
+      buffer.splice(0, 1)
+    }
+  }
+
+  const remove: BoundedBuffer<T>['remove'] = (callback: (arg: T) => void) => {
+    removeItem(buffer, callback)
+  }
+
+  const drain = (arg: T) => {
+    buffer.forEach((callback) => callback(arg))
+    buffer.length = 0
+  }
+
+  return {
+    add,
+    remove,
+    drain,
+  }
+}

package/src/tools/catchUserErrors.ts

@@ -0,0 +1,11 @@
+import { display } from './display'
+
+export function catchUserErrors<Args extends any[], R>(fn: (...args: Args) => R, errorMsg: string) {
+  return (...args: Args) => {
+    try {
+      return fn(...args)
+    } catch (err) {
+      display.error(errorMsg, err)
+    }
+  }
+}

package/src/tools/display.ts

@@ -0,0 +1,56 @@
+/* eslint-disable local-rules/disallow-side-effects */
+/**
+ * Keep references on console methods to avoid triggering patched behaviors
+ *
+ * NB: in some setup, console could already be patched by another SDK.
+ * In this case, some display messages can be sent by the other SDK
+ * but we should be safe from infinite loop nonetheless.
+ */
+
+export const ConsoleApiName = {
+  log: 'log',
+  debug: 'debug',
+  info: 'info',
+  warn: 'warn',
+  error: 'error',
+} as const
+
+export type ConsoleApiName = (typeof ConsoleApiName)[keyof typeof ConsoleApiName]
+
+interface Display {
+  debug: typeof console.debug
+  log: typeof console.log
+  info: typeof console.info
+  warn: typeof console.warn
+  error: typeof console.error
+}
+
+/**
+ * When building JS bundles, some users might use a plugin[1] or configuration[2] to remove
+ * "console.*" references. This causes some issue as we expect `console.*` to be defined.
+ * As a workaround, let's use a variable alias, so those expressions won't be taken into account by
+ * simple static analysis.
+ *
+ * [1]: https://babeljs.io/docs/babel-plugin-transform-remove-console/
+ * [2]: https://github.com/terser/terser#compress-options (look for drop_console)
+ */
+export const globalConsole = console
+
+export const originalConsoleMethods = {} as Display
+Object.keys(ConsoleApiName).forEach((name) => {
+  originalConsoleMethods[name as ConsoleApiName] = globalConsole[name as ConsoleApiName]
+})
+
+const PREFIX = 'Kubsesense Browser SDK:'
+
+export const display: Display = {
+  debug: originalConsoleMethods.debug.bind(globalConsole, PREFIX),
+  log: originalConsoleMethods.log.bind(globalConsole, PREFIX),
+  info: originalConsoleMethods.info.bind(globalConsole, PREFIX),
+  warn: originalConsoleMethods.warn.bind(globalConsole, PREFIX),
+  error: originalConsoleMethods.error.bind(globalConsole, PREFIX),
+}
+
+export const DOCS_ORIGIN = 'https://docs.kubesense.ai'
+export const DOCS_TROUBLESHOOTING = `${DOCS_ORIGIN}/rum/browser/troubleshooting`
+export const MORE_DETAILS = 'More details:'