@kubesense/kubesense-browser-core 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubesense/kubesense-browser-core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Core utilities shared across the Kubesense Browser SDK (session management, transport, configuration, and context).",
   "license": "Apache-2.0",
   "keywords": [
@@ -35,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "af1a0950e2441f45b4303b2dc17b09f9cd0d999d"
+  "gitHead": "5b90a5a0ea4ee972c079b9a55c45d05c44f14688"
 }

package/src/domain/configuration/configuration.ts

@@ -47,27 +47,27 @@ export type TraceContextInjection = (typeof TraceContextInjection)[keyof typeof
 
 export interface InitConfiguration {
   /**
-   * The client token for Kubsesense. Required for authenticating your application with Kubsesense.
-   * 
+   * The client token for KubeSense. Required for authenticating your application with KubeSense.
+   *
    * @category Authentication
    */
   clientToken: string
   /**
-   * A callback function that can be used to modify events before they are sent to Kubsesense.
-   * 
+   * A callback function that can be used to modify events before they are sent to KubeSense.
+   *
    *  @category Data Collection
    */
   beforeSend?: GenericBeforeSendCallback | undefined
   /**
    * The percentage of sessions tracked. A value between 0 and 100.
-   * 
+   *
    * @category Data Collection
    * @defaultValue 100
    */
   sessionSampleRate?: number | undefined
   /**
    * The percentage of telemetry events sent. A value between 0 and 100.
-   * 
+   *
    * @category Data Collection
    * @defaultValue 20
    */
@@ -82,7 +82,7 @@ export interface InitConfiguration {
    * Which storage strategy to use for persisting sessions. Can be either 'cookie' or 'local-storage'.
    *
    * Important: If you are using the RUM and Logs Browser SDKs, this option must be configured with identical values
-   * 
+   *
    * @category Session Persistence
    * @defaultValue "cookie"
    */
@@ -109,7 +109,7 @@ export interface InitConfiguration {
   storeContextsAcrossPages?: boolean | undefined
   /**
    * Set the initial user tracking consent state.
-   * 
+   *
    * @category Privacy
    * @defaultValue granted
    */
@@ -125,12 +125,12 @@ export interface InitConfiguration {
   // transport options
   /**
    * Optional proxy URL, for example: https://www.proxy.com/path.
-   * 
+   *
    * @category Transport
    */
   proxy?: string | ProxyFn | undefined
   /**
-   * 
+   *
    * @category Transport
    * @defaultValue rum.kubesense.ai
    */
@@ -138,20 +138,20 @@ export interface InitConfiguration {
 
   // tag and context options
   /**
-   * The service name for your application. 
-   * 
+   * The service name for your application.
+   *
    *  @category Data Collection
    */
   service?: string | undefined | null
   /**
    * The application’s environment, for example: prod, pre-prod, and staging.
-   * 
+   *
    *  @category Data Collection
    */
   env?: string | undefined | null
   /**
-   * The application’s version, for example: 1.2.3, 6c44da20, and 2020.02.13. 
-   * 
+   * The application’s version, for example: 1.2.3, 6c44da20, and 2020.02.13.
+   *
    *  @category Data Collection
    */
   version?: string | undefined | null
@@ -212,7 +212,7 @@ export interface InitConfiguration {
    */
   datacenter?: string
   /**
-   * [Internal option] Kubsesense internal analytics subdomain
+   * [Internal option] KubeSense internal analytics subdomain
    * @internal
    */
   // TODO next major: remove this option and replace usages by proxyFn
@@ -299,9 +299,9 @@ function isString(tag: unknown, tagName: string): tag is string | undefined | nu
   return true
 }
 
-function isKubsesenseSite(site: unknown) {
+function isKubeSenseSite(site: unknown) {
   if (site && typeof site === 'string' && !/(kubesense|tyke)/.test(site)) {
-    display.error(`Site should be a valid Kubsesense site. ${MORE_DETAILS} ${DOCS_ORIGIN}/getting_started/site/.`)
+    display.error(`Site should be a valid KubeSense site. ${MORE_DETAILS} ${DOCS_ORIGIN}/getting_started/site/.`)
     return false
   }
   return true
@@ -333,7 +333,7 @@ export function validateAndBuildConfiguration(
   }
 
   if (
-    // !isKubsesenseSite(initConfiguration.kubesenseRumEndpoint) ||
+    // !isKubeSenseSite(initConfiguration.kubesenseRumEndpoint) ||
     !isSampleRate(initConfiguration.sessionSampleRate, 'Session') ||
     !isSampleRate(initConfiguration.telemetrySampleRate, 'Telemetry') ||
     !isSampleRate(initConfiguration.telemetryConfigurationSampleRate, 'Telemetry Configuration') ||

package/src/domain/configuration/index.ts

@@ -8,5 +8,20 @@ export {
 } from './configuration'
 export type { EndpointBuilder, TrackType } from './endpointBuilder'
 export { createEndpointBuilder, buildEndpointHost } from './endpointBuilder'
+export type { RemoteSdkConfig, RemoteSdkConfigFeatures } from './remoteSdkConfig'
+export {
+  SDK_CONFIG_CACHE_KEY,
+  SDK_CONFIG_PATH,
+  buildSdkConfigEndpoint,
+  clearCachedSdkConfig,
+  getCachedSdkConfig,
+  parseSdkConfig,
+  readBoolean,
+  readEnum,
+  readSampleRate,
+  readString,
+  refreshSdkConfig,
+  setCachedSdkConfig,
+} from './remoteSdkConfig'
 export * from '../intakeSites'
 export { computeTransportConfiguration, isIntakeUrl } from './transportConfiguration'

package/src/domain/configuration/remoteSdkConfig.ts

@@ -0,0 +1,213 @@
+import { generateUUID } from '../../tools/utils/stringUtils'
+import { display } from '../../tools/display'
+import { monitorError } from '../../tools/monitor'
+import type { InitConfiguration } from './configuration'
+import { buildEndpointHost } from './endpointBuilder'
+
+/**
+ * Dashboard-managed SDK settings, served by the Kubesense collector.
+ *
+ * The document is fetched asynchronously *after* the SDK has started and cached in local
+ * storage, so it costs nothing on the initialization path. Cached values are applied on the
+ * next page load — SDK configuration is frozen at `init()` time by design.
+ */
+
+export const SDK_CONFIG_CACHE_KEY = '_kubesense_sdk_config'
+export const SDK_CONFIG_PATH = '/rum/api/v1/sdk-config'
+
+/** Give up rather than let a hung request keep a page-load handle alive. */
+export const SDK_CONFIG_FETCH_TIMEOUT = 10_000
+
+/**
+ * A remote configuration document. Every field is optional: a missing (or invalid) field means
+ * "leave the SDK default alone", so a malformed document can never take an application away
+ * from its defaults.
+ */
+export interface RemoteSdkConfig {
+  /** Free-form number for dashboard bookkeeping. Not interpreted by the SDK. */
+  version?: number
+  features?: RemoteSdkConfigFeatures
+  rum?: { [key: string]: unknown }
+  sessionReplay?: { [key: string]: unknown }
+  profiling?: { [key: string]: unknown }
+  logs?: { [key: string]: unknown }
+  [key: string]: unknown
+}
+
+export interface RemoteSdkConfigFeatures {
+  rum?: boolean
+  sessionReplay?: boolean
+  profiling?: boolean
+  logs?: boolean
+}
+
+/**
+ * Read the cached document. Synchronous, never touches the network, and never throws: a
+ * corrupted or unavailable cache resolves to `undefined` (pure SDK defaults).
+ */
+export function getCachedSdkConfig(): RemoteSdkConfig | undefined {
+  let raw: string | null
+  try {
+    raw = localStorage.getItem(SDK_CONFIG_CACHE_KEY)
+  } catch {
+    // Local storage can be unavailable (disabled, quota, sandboxed iframe).
+    return undefined
+  }
+
+  if (!raw) {
+    return undefined
+  }
+
+  const config = parseSdkConfig(raw)
+  if (!config) {
+    // Drop a document we can no longer read so we stop paying for it on every page load.
+    clearCachedSdkConfig()
+  }
+  return config
+}
+
+export function setCachedSdkConfig(rawConfig: string) {
+  try {
+    localStorage.setItem(SDK_CONFIG_CACHE_KEY, rawConfig)
+  } catch {
+    // Ignore: caching is an optimization, not a requirement.
+  }
+}
+
+export function clearCachedSdkConfig() {
+  try {
+    localStorage.removeItem(SDK_CONFIG_CACHE_KEY)
+  } catch {
+    // Ignore.
+  }
+}
+
+/**
+ * A document is only usable if it is a JSON object. Anything else (array, primitive, invalid
+ * JSON) is rejected wholesale.
+ */
+export function parseSdkConfig(raw: string): RemoteSdkConfig | undefined {
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return undefined
+    }
+    return parsed as RemoteSdkConfig
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The config endpoint deliberately carries the same query parameters as the intake, for two
+ * reasons: it authenticates without a custom header (which would force a CORS preflight), and
+ * it makes `isIntakeUrl()` return true, so the SDK never reports its own configuration request
+ * as a resource or a network error.
+ */
+export function buildSdkConfigEndpoint(initConfiguration: InitConfiguration, applicationId?: string): string {
+  const host = buildEndpointHost('rum', initConfiguration)
+  const parameters = [
+    'ksource=browser',
+    `kubesense-api-key=${encodeURIComponent(initConfiguration.clientToken)}`,
+    `kubesense-request-id=${generateUUID()}`,
+  ]
+  if (applicationId) {
+    // The collector resolves the application from this parameter first, falling back to the
+    // token -> application mapping. Sending it makes per-application configuration explicit.
+    parameters.push(`application_id=${encodeURIComponent(applicationId)}`)
+  }
+  return `https://${host}${SDK_CONFIG_PATH}?${parameters.join('&')}`
+}
+
+/**
+ * Fetch the document and refresh the cache for the *next* page load. Fire-and-forget: any
+ * failure (offline, 404 because the collector has no config file, 401, timeout, malformed
+ * body) leaves the existing cache untouched.
+ *
+ * The response is validated before it overwrites the cache, so a half-written document on the
+ * collector can never poison a client.
+ */
+export function refreshSdkConfig(initConfiguration: InitConfiguration, applicationId?: string): Promise<void> {
+  if (typeof fetch !== 'function') {
+    return Promise.resolve()
+  }
+
+  let endpoint: string
+  try {
+    endpoint = buildSdkConfigEndpoint(initConfiguration, applicationId)
+  } catch (error) {
+    monitorError(error)
+    return Promise.resolve()
+  }
+
+  return fetch(endpoint, {
+    method: 'GET',
+    // Configuration is not user data: never attach cookies to it.
+    credentials: 'omit',
+    mode: 'cors',
+    // Always ask the collector, never a proxy cache — dashboard edits must propagate.
+    cache: 'no-store',
+    signal: createTimeoutSignal(SDK_CONFIG_FETCH_TIMEOUT),
+  })
+    .then((response) => {
+      if (!response.ok) {
+        // 404 simply means "no configuration published"; keep whatever we already had.
+        return undefined
+      }
+      return response.text()
+    })
+    .then((rawConfig) => {
+      if (rawConfig === undefined) {
+        return
+      }
+      if (!parseSdkConfig(rawConfig)) {
+        display.warn('Remote SDK configuration is not a valid JSON object, ignoring it.')
+        return
+      }
+      setCachedSdkConfig(rawConfig)
+    })
+    .catch(() => {
+      // Network failures are expected and must stay silent: the SDK keeps running on the
+      // cached configuration, or on its defaults.
+    })
+}
+
+function createTimeoutSignal(timeout: number): AbortSignal | undefined {
+  // AbortSignal.timeout is not available on all supported browsers; without it the fetch
+  // simply runs to completion, which is acceptable for a fire-and-forget request.
+  if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') {
+    return AbortSignal.timeout(timeout)
+  }
+  return undefined
+}
+
+/* ------------------------------------------------------------------------------------------
+ * Defensive readers
+ *
+ * Each returns `undefined` when the value is missing or unusable, which callers translate into
+ * "do not override the SDK default".
+ * ---------------------------------------------------------------------------------------- */
+
+export function readBoolean(source: { [key: string]: unknown } | undefined, key: string): boolean | undefined {
+  const value = source?.[key]
+  return typeof value === 'boolean' ? value : undefined
+}
+
+export function readSampleRate(source: { [key: string]: unknown } | undefined, key: string): number | undefined {
+  const value = source?.[key]
+  return typeof value === 'number' && isFinite(value) && value >= 0 && value <= 100 ? value : undefined
+}
+
+export function readString(source: { [key: string]: unknown } | undefined, key: string): string | undefined {
+  const value = source?.[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+export function readEnum<T extends string>(
+  source: { [key: string]: unknown } | undefined,
+  key: string,
+  allowedValues: readonly T[]
+): T | undefined {
+  const value = source?.[key]
+  return typeof value === 'string' && (allowedValues as readonly string[]).includes(value) ? (value as T) : undefined
+}

package/src/domain/contexts/userContext.ts

@@ -16,6 +16,7 @@ export interface User {
   id?: string | undefined
   email?: string | undefined
   name?: string | undefined
+  mobile?: string | undefined
   [key: string]: unknown
 }
 
@@ -143,6 +144,10 @@ export function buildUserContextManager() {
       id: { type: 'string' },
       name: { type: 'string' },
       email: { type: 'string' },
+      // Coerced to string like the other identity fields: phone numbers are
+      // routinely passed as JS numbers, and the collector unmarshals
+      // usr.mobile into a string column.
+      mobile: { type: 'string' },
     },
   })
 }

package/src/index.ts

@@ -1,4 +1,5 @@
 export type { Configuration, InitConfiguration, EndpointBuilder, ProxyFn } from './domain/configuration'
+export type { RemoteSdkConfig, RemoteSdkConfigFeatures } from './domain/configuration'
 export {
   validateAndBuildConfiguration,
   DefaultPrivacyLevel,
@@ -10,6 +11,18 @@ export {
   INTAKE_SITE_PROD,
   INTAKE_SITE_STAGING,
   isIntakeUrl,
+  SDK_CONFIG_CACHE_KEY,
+  SDK_CONFIG_PATH,
+  buildSdkConfigEndpoint,
+  clearCachedSdkConfig,
+  getCachedSdkConfig,
+  parseSdkConfig,
+  readBoolean,
+  readEnum,
+  readSampleRate,
+  readString,
+  refreshSdkConfig,
+  setCachedSdkConfig,
 } from './domain/configuration'
 export * from './domain/intakeSites'
 export type { TrackingConsentState } from './domain/trackingConsent'

package/src/tools/display.ts

@@ -41,7 +41,7 @@ Object.keys(ConsoleApiName).forEach((name) => {
   originalConsoleMethods[name as ConsoleApiName] = globalConsole[name as ConsoleApiName]
 })
 
-const PREFIX = 'Kubsesense Browser SDK:'
+const PREFIX = 'KubeSense Browser SDK:'
 
 export const display: Display = {
   debug: originalConsoleMethods.debug.bind(globalConsole, PREFIX),

package/src/transport/eventBridge.ts

@@ -2,10 +2,10 @@ import { getGlobalObject } from '../tools/globalObject'
 import type { DefaultPrivacyLevel } from '../domain/configuration'
 
 export interface BrowserWindowWithEventBridge extends Window {
-  KubsesenseEventBridge?: KubsesenseEventBridge
+  KubeSenseEventBridge?: KubeSenseEventBridge
 }
 
-export interface KubsesenseEventBridge {
+export interface KubeSenseEventBridge {
   getCapabilities?(): string
   getPrivacyLevel?(): DefaultPrivacyLevel
   getAllowedWebViewHosts(): string
@@ -56,5 +56,5 @@ export function canUseEventBridge(currentHost = getGlobalObject<Window>().locati
 }
 
 function getEventBridgeGlobal() {
-  return getGlobalObject<BrowserWindowWithEventBridge>().KubsesenseEventBridge
+  return getGlobalObject<BrowserWindowWithEventBridge>().KubeSenseEventBridge
 }

package/src/transport/index.ts

@@ -1,6 +1,6 @@
 export type { BandwidthStats, HttpRequest, HttpRequestEvent, Payload, RetryInfo } from './httpRequest'
 export { createHttpRequest } from './httpRequest'
-export type { BrowserWindowWithEventBridge, KubsesenseEventBridge } from './eventBridge'
+export type { BrowserWindowWithEventBridge, KubeSenseEventBridge } from './eventBridge'
 export { canUseEventBridge, bridgeSupports, getEventBridge, BridgeCapability } from './eventBridge'
 export { createBatch } from './batch'
 export type { FlushController, FlushEvent, FlushReason } from './flushController'