@kubesense/kubesense-browser-rum-core 1.7.0 → 2.0.0-beta.1

package/src/domain/configuration/configuration.ts

@@ -1,27 +1,51 @@
-import type { Configuration, InitConfiguration, MatchOption, RawTelemetryConfiguration } from '@kubesense/kubesense-browser-core'
+import type { InitConfiguration, RawTelemetryConfiguration } from '@kubesense/kubesense-browser-core'
 import {
-  getType,
-  isMatchOption,
+  canUseEventBridge,
+  catchUserErrors,
   serializeConfiguration,
   DefaultPrivacyLevel,
   TraceContextInjection,
   display,
-  objectHasValue,
-  validateAndBuildConfiguration,
-  isSampleRate,
   isNumber,
   isNonEmptyArray,
+  BROWSER_CORE_SCHEMA,
 } from '@kubesense/kubesense-browser-core'
+import { isIndexableObject, isMatchOption } from '@kubesense/kubesense-js-core/util'
+import { validateAndBuildConfiguration } from '@kubesense/kubesense-js-core/configuration'
+import type { InferredConfig, MatchOption } from '@kubesense/kubesense-js-core/configuration'
 import type { RumEventDomainContext } from '../../domainContext.types'
 import type { RumEvent } from '../../rumEvent.types'
+import type { SdkName } from '../contexts/defaultContext'
 import type { RumPlugin } from '../plugins'
-import { isTracingOption } from '../tracing/tracer'
 import type { PropagatorType, TracingOption } from '../tracing/tracer.types'
+import { getRemoteConfigurationId } from './remoteConfiguration'
+import type { RemoteConfigurationMetadata } from './remoteConfigurationCache'
 import type { SessionReplayRoutes } from './sessionReplayRoutes'
-import { validateSessionReplayRoutes } from './sessionReplayRoutes'
+
+// replaced at build time
+declare const __BUILD_ENV__SDK_SETUP__: string
 
 export const DEFAULT_PROPAGATOR_TYPES: PropagatorType[] = ['tracecontext', 'kubesense']
 
+/**
+ * Default list of headers collected on resource events when {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders}
+ * is set to `true`.
+ */
+export const DEFAULT_TRACKED_RESOURCE_HEADERS = [
+  'cache-control',
+  'etag',
+  'age',
+  'expires',
+  'content-type',
+  'content-encoding',
+  'vary',
+  'content-length',
+  'server-timing',
+  'x-cache',
+  'cf-cache-status',
+  'x-vercel-cache',
+] as const
+
 /**
  * Init Configuration for the RUM browser SDK.
  *
@@ -33,6 +57,7 @@ export const DEFAULT_PROPAGATOR_TYPES: PropagatorType[] = ['tracecontext', 'kube
  * kubesenseSdk.init({
  *   applicationId: '<KUBESENSE_APPLICATION_ID>',
  *   clientToken: '<KUBESENSE_CLIENT_TOKEN>',
+ *   kubesenseRumEndpoint: '<KUBESENSE_RUM_ENDPOINT>',
  *   // ...
  * })
  * ```
@@ -41,6 +66,7 @@ export const DEFAULT_PROPAGATOR_TYPES: PropagatorType[] = ['tracecontext', 'kube
  * KUBESENSE_SDK.init({
  *   applicationId: '<KUBESENSE_APPLICATION_ID>',
  *   clientToken: '<KUBESENSE_CLIENT_TOKEN>',
+ *   kubesenseRumEndpoint: '<KUBESENSE_RUM_ENDPOINT>',
  *   ...
  * })
  * ```
@@ -54,11 +80,21 @@ export interface RumInitConfiguration extends InitConfiguration {
    */
   applicationId: string
 
+  /**
+   * The service name for your application. Follows the [tag syntax requirements](https://docs.kubesense.ai/getting_started/tagging/#define-tags).
+   *
+   * `allowedTracingUrls` still requires an explicitly configured service.
+   *
+   * @category Data Collection
+   * @defaultValue the `applicationId`
+   */
+  service?: string | undefined | null
+
   /**
    * Whether to propagate user and account IDs in the baggage header of trace requests.
    *
    * @category Tracing
-   * @defaultValue false
+   * @defaultValue true
    */
   propagateTraceBaggage?: boolean | undefined
 
@@ -72,11 +108,8 @@ export interface RumInitConfiguration extends InitConfiguration {
    * See [Enrich And Control Browser RUM Data With beforeSend](https://docs.kubesense.ai/real_user_monitoring/guide/enrich-and-control-rum-data) for further information.
    *
    * @category Data Collection
-   * @param event - The RUM event
-   * @param context - The RUM event domain context providing access to native browser data based on the event type (e.g. error, performance entry).
-   * @returns true if the event should be sent to Kubesense, false otherwise
    */
-  beforeSend?: ((event: RumEvent, context: RumEventDomainContext) => boolean) | undefined
+  beforeSend?: RumBeforeSend | undefined
 
   /**
    * A list of request origins ignored when computing the page activity.
@@ -85,7 +118,7 @@ export interface RumInitConfiguration extends InitConfiguration {
   excludedActivityUrls?: MatchOption[] | undefined
 
   /**
-   * URL pointing to the Kubesense Browser SDK Worker JavaScript file. The URL can be relative or absolute, but is required to have the same origin as the web application.
+   * URL pointing to the KubeSense Browser SDK Worker JavaScript file. The URL can be relative or absolute, but is required to have the same origin as the web application.
    * See [Content Security Policy guidelines](https://docs.kubesense.ai/integrations/content_security_policy_logs/?tab=firefox#use-csp-with-real-user-monitoring-and-session-replay) for further information.
    *
    * @category Transport
@@ -93,7 +126,7 @@ export interface RumInitConfiguration extends InitConfiguration {
   workerUrl?: string
 
   /**
-   * Compress requests sent to the Kubesense intake to reduce bandwidth usage when sending large amounts of data. The compression is done in a Worker thread.
+   * Compress requests sent to the KubeSense intake to reduce bandwidth usage when sending large amounts of data. The compression is done in a Worker thread.
    * See [Content Security Policy guidelines](https://docs.kubesense.ai/integrations/content_security_policy_logs/?tab=firefox#use-csp-with-real-user-monitoring-and-session-replay) for further information.
    *
    * @category Transport
@@ -101,12 +134,25 @@ export interface RumInitConfiguration extends InitConfiguration {
   compressIntakeRequests?: boolean | undefined
 
   /**
-   * [Internal option] Id of the remote configuration
+   * [Internal option] Id of the remote configuration.
+   * Prefer `remoteConfiguration.id` for the non-blocking cache-and-reload path.
    *
    * @internal
    */
   remoteConfigurationId?: string | undefined
 
+  /**
+   * [Internal option] Remote configuration descriptor. By default the SDK reads a cached
+   * configuration synchronously and refreshes it in the background. Set `sync: true` to fall back
+   * to the legacy blocking fetch. Set `required: true` to prevent the SDK from starting on the
+   * current page load when the remote configuration cache is empty or unreadable (the background
+   * fetch still runs to populate the cache for the next load). Ignored when `sync: true` is set
+   * or when the legacy `remoteConfigurationId` field is used.
+   *
+   * @internal
+   */
+  remoteConfiguration?: { id: string; sync?: boolean; required?: boolean } | undefined
+
   /**
    * [Internal option] set a proxy URL for the remote configuration
    *
@@ -115,17 +161,47 @@ export interface RumInitConfiguration extends InitConfiguration {
   remoteConfigurationProxy?: string | undefined
 
   /**
-   * Enable dashboard-managed SDK settings served by the Kubesense collector.
+   * Enable dashboard-managed SDK settings served by the KubeSense collector.
    *
    * The configuration document is fetched asynchronously after the SDK starts and cached in
    * local storage, so it never delays initialization. Cached settings are applied on the next
    * page load. Local `init()` values are used until a document has been fetched, and any
    * setting absent from the document keeps its local value.
    *
+   * @category Data Collection
    * @defaultValue false
    */
   enableRemoteSdkConfiguration?: boolean | undefined
 
+  /**
+   * Restrict Session Replay recording to specific routes.
+   *
+   * Recording starts and stops as the user navigates: it runs only while the current route
+   * matches `include` (when provided) and does not match `exclude`. Rules are matched against
+   * the path (`pathname` + `search` + `hash`), and string entries match by prefix, so
+   * `/checkout` also covers `/checkout/payment`.
+   *
+   * These rules only narrow recording — a session that was not sampled in by
+   * `sessionReplaySampleRate` is never recorded, whatever the routes say.
+   *
+   * @category Session Replay
+   * @example
+   * ```ts
+   * sessionReplayRoutes: { include: ['/checkout', '/signup'], exclude: ['/checkout/card'] }
+   * ```
+   */
+  sessionReplayRoutes?: SessionReplayRoutes | undefined
+
+  /**
+   * A list of domains to treat as first-party in resource provider classification.
+   * Accepts strings (exact hostname match), RegExp, or functions.
+   * The current page hostname is always treated as first-party.
+   *
+   * @category Data Collection
+   * @example ['api.myapp.com', /\.myapp\.com$/, (host) => host.endsWith('.internal')]
+   */
+  firstPartyDomains?: MatchOption[] | undefined
+
   // tracing options
   /**
    * A list of request URLs used to inject tracing headers.
@@ -133,13 +209,15 @@ export interface RumInitConfiguration extends InitConfiguration {
    *
    * @category Tracing
    */
-  allowedTracingUrls?: Array<MatchOption | TracingOption> | undefined
+  allowedTracingUrls?:
+    Array<MatchOption | { match: MatchOption; propagatorTypes?: PropagatorType[] | null | undefined }> | undefined
 
   /**
    * The percentage of requests to trace: 100 for all, 0 for none.
    * See [Connect RUM and Traces](https://docs.kubesense.ai/real_user_monitoring/platform/connect_rum_and_traces/?tab=browserrum) for further information.
    *
    * @category Tracing
+   * @defaultValue 100
    */
   traceSampleRate?: number | undefined
   /**
@@ -159,65 +237,99 @@ export interface RumInitConfiguration extends InitConfiguration {
    * See [Replay Privacy Options](https://docs.kubesense.ai/real_user_monitoring/session_replay/browser/privacy_options) for further information.
    *
    * @category Privacy
-   * @defaultValue mask
+   * @defaultValue mask-user-input
    */
   defaultPrivacyLevel?: DefaultPrivacyLevel | undefined
 
   /**
-   * If you are accessing Kubesense through a custom subdomain, you can set `subdomain` to include your custom domain in the `getSessionReplayLink()` returned URL .
+   * If you are accessing KubeSense through a custom subdomain, you can set `subdomain` to include your custom domain in the `getSessionReplayLink()` returned URL .
    *
    * See [Connect Session Replay To Your Third-Party Tools](https://docs.kubesense.ai/real_user_monitoring/guide/connect-session-replay-to-your-third-party-tools) for further information.
    *
+   * @category Session Replay
    */
   subdomain?: string
 
   /**
-   * The percentage of tracked sessions with [Browser RUM & Session Replay pricing](https://www.kubesense.ai/pricing/?product=real-user-monitoring--session-replay#real-user-monitoring--session-replay) features: 100 for all, 0 for none.
+   * The percentage of tracked sessions with [Browser RUM & Session Replay pricing](https://rum.kubesense.ai/pricing/?product=real-user-monitoring--session-replay#real-user-monitoring--session-replay) features: 100 for all, 0 for none.
    *
    * See [Configure Your Setup For Browser RUM and Browser RUM & Session Replay Sampling](https://docs.kubesense.ai/real_user_monitoring/guide/sampling-browser-plans) for further information.
    *
    * @category Session Replay
+   * @defaultValue 0
    */
   sessionReplaySampleRate?: number | undefined
 
   /**
-   * If the session is sampled for Session Replay, only start the recording when `startSessionReplayRecording()` is called, instead of at the beginning of the session. Default: if startSessionReplayRecording is 0, true; otherwise, false.
+   * If the session is sampled for Session Replay, only start the recording when `startSessionReplayRecording()` is called, instead of at the beginning of the session.
    *
    * See [Session Replay Usage](https://docs.kubesense.ai/real_user_monitoring/session_replay/browser/#usage) for further information.
    *
    * @category Session Replay
+   * @defaultValue false
    */
   startSessionReplayRecordingManually?: boolean | undefined
 
   /**
-   * Restrict Session Replay recording to specific routes.
+   * Records `<canvas>` content (most chart libraries draw on one) in Session Replay as captured frames.
+   * Canvas recording is disabled when this option is omitted.
    *
-   * Recording starts and stops as the user navigates: it runs only while the current route
-   * matches `include` (when provided) and does not match `exclude`. Rules are matched against
-   * the path (`pathname` + `search` + `hash`), and string entries match by prefix, so
-   * `/checkout` also covers `/checkout/payment`.
+   * A canvas is captured only when its privacy level is `allow` — set with `data-kubesense-privacy="allow"`
+   * or the `kubesense-privacy-allow` class on it or an ancestor — and only when its content changed.
+   * Frames are WebP images (PNG where the browser cannot encode WebP), uploaded next to the replay
+   * segments and deduplicated by content.
    *
-   * These rules only narrow recording — a session that was not sampled in by
-   * `sessionReplaySampleRate` is never recorded, whatever the routes say.
+   * `quality` picks a preset; the other fields override single values of that preset.
    *
    * @category Session Replay
-   * @example
-   * ```ts
-   * sessionReplayRoutes: { include: ['/checkout', '/signup'], exclude: ['/checkout/card'] }
-   * ```
    */
-  sessionReplayRoutes?: SessionReplayRoutes | undefined
+  sessionReplayCanvasRecording?:
+    | {
+        /**
+         * Enables recording canvas elements in Session Replay.
+         */
+        enable: boolean
+
+        /**
+         * Trades frame rate and image resolution for bandwidth. See {@link CanvasRecordingQuality}.
+         *
+         * @defaultValue 'medium'
+         */
+        quality?: CanvasRecordingQuality | undefined
+
+        /**
+         * Overrides the preset's maximum number of frames captured per second, between 0 and 8. `0`
+         * stops capturing frames.
+         */
+        maxFramesPerSecond?: number | undefined
+
+        /**
+         * Overrides the preset's longest side of a captured frame, in pixels, between 1 and 1280. Larger
+         * canvases are downscaled proportionally.
+         */
+        maxImageDimension?: number | undefined
+
+        /**
+         * Overrides the preset's size of the thumbnail compared to detect a changed canvas, in pixels,
+         * between 1 and 100.
+         */
+        hashingMaxDimension?: number | undefined
+      }
+    | undefined
 
   /**
    * Enables privacy control for action names.
    *
    * @category Privacy
+   * @defaultValue true
    */
-  enablePrivacyForActionName?: boolean | undefined // TODO next major: remove this option and make privacy for action name the default behavior
+  enablePrivacyForActionName?: boolean | undefined
 
   /**
    * Enables automatic collection of users actions.
    *
+   * Add `data-dd-ignore-frustration` without a value, or set it to `all`, to ignore all frustration signals for an element and its descendants. To ignore specific signals, use a space-separated list of `rage-click`, `dead-click`, and `error-click`.
+   *
    * See [Tracking User Actions](https://docs.kubesense.ai/real_user_monitoring/browser/tracking_user_actions) for further information.
    *
    * @category Data Collection
@@ -242,14 +354,6 @@ export interface RumInitConfiguration extends InitConfiguration {
    */
   trackViewsManually?: boolean | undefined
 
-  /**
-   * Enable the creation of dedicated views for pages restored from the Back-Forward cache.
-   *
-   * @category Data Collection
-   * @defaultValue false
-   */
-  trackBfcacheViews?: boolean | undefined
-
   /**
    * Enables collection of resource events.
    *
@@ -259,24 +363,47 @@ export interface RumInitConfiguration extends InitConfiguration {
   trackResources?: boolean | undefined
 
   /**
-   * Enables collection of long task events.
+   * Enables collection of request and response headers on resource events.
+   *
+   * - `true`: collect {@link DEFAULT_TRACKED_RESOURCE_HEADERS} for all URLs, both directions
+   * - `MatchHeader[]`: each {@link MatchHeader} targets a header name, with optional URL scope
+   * (`url`), value extraction (`extractor`), and `location`. When `name` is omitted, the matcher
+   * applies to {@link DEFAULT_TRACKED_RESOURCE_HEADERS}. By default, both request and response
+   * headers are captured; set `location` to `'request'` or `'response'` to restrict to one.
+   *
+   * Headers whose names match a built-in sensitive-data pattern are always dropped, regardless
+   * of the configured matchers. The pattern blocks headers whose names contain: `token`, `cookie`,
+   * `secret`, `authorization`, `api-key`, `secret-key`, `access-key`, `app-key`, `client-ip`,
+   * `connecting-ip`, `real-ip`, or `forwarded`.
    *
    * @category Data Collection
-   * @defaultValue true
+   * @defaultValue false (disabled)
+   * @example
+   * // Collect default headers plus custom ones for all URLs
+   * trackResourceHeaders: [{}, { name: 'x-request-id' }]
+   * @example
+   * // Collect default headers from responses only
+   * trackResourceHeaders: [{ location: 'response' }]
+   * @example
+   * // URL-scoped rule: capture specific response headers only for calls to /api
+   * trackResourceHeaders: [{ url: /\/api\//, name: 'cache-control', location: 'response' }]
+   * @example
+   * // Extract a partial value from a header
+   * trackResourceHeaders: [{ url: /\/api\//, name: 'server-timing', extractor: /dur=(\d+)/, location: 'response' }]
    */
-  trackLongTasks?: boolean | undefined
+  trackResourceHeaders?: boolean | MatchHeader[] | undefined
 
   /**
-   * Enables early request collection before resource timing entries are available.
+   * Enables collection of long task events.
    *
    * @category Data Collection
-   * @defaultValue false
+   * @defaultValue true
    */
-  trackEarlyRequests?: boolean | undefined
+  trackLongTasks?: boolean | undefined
 
   /**
    * List of plugins to enable. The plugins API is unstable and experimental, and may change without
-   * notice. Please use only plugins provided by Kubesense matching the version of the SDK you are
+   * notice. Please use only plugins provided by KubeSense matching the version of the SDK you are
    * using.
    */
   plugins?: RumPlugin[] | undefined
@@ -304,170 +431,334 @@ export interface RumInitConfiguration extends InitConfiguration {
   allowedGraphQlUrls?: Array<MatchOption | GraphQlUrlOption> | undefined
 
   /**
-   * A list of domains to treat as first-party in resource provider classification.
-   * Accepts strings (exact hostname match), RegExp, or functions.
-   * The current page hostname is always treated as first-party.
+   * Enable partial view updates, which reduces bandwidth by sending only changed
+   * fields instead of full view events on intermediate updates.
    *
-   * @category Data Collection
-   * @example ['api.myapp.com', /\.myapp\.com$/, (host) => host.endsWith('.internal')]
+   * Enabled by default when the SDK is loaded from the CDN and no `proxy` is configured.
+   * Disabled by default otherwise, because a proxy may not forward the `view_update` event type.
+   *
+   * @category Beta
    */
-  firstPartyDomains?: MatchOption[] | undefined
+  betaEnableViewUpdates?: boolean | undefined
+
+  /**
+   * Enables collection of WebSocket resource events.
+   *
+   * Warning: enabling this option introduces WebSocket resource events to the `beforeSend` hook.
+   * Their domain context is WebSocket-specific and does not contain the XHR, Fetch, or performance
+   * entry fields available on regular resource events. Narrow the context using the existing
+   * `isManual` and `isWebSocket` discriminants before accessing those fields.
+   *
+   * @category Beta
+   */
+  betaTrackWebSockets?: boolean | undefined
 }
 
-export type HybridInitConfiguration = Omit<RumInitConfiguration, 'applicationId' | 'clientToken'>
+/**
+ * Recording quality presets for canvas capture. See {@link RumInitConfiguration.sessionReplayCanvasRecording}.
+ *
+ * | Preset   | Frames per second | Longest side | WebP quality |
+ * | -------- | ----------------- | ------------ | ------------ |
+ * | `low`    | 1                 | 600 px       | 0.3          |
+ * | `medium` | 4                 | 1000 px      | 0.5          |
+ * | `high`   | 8                 | 1280 px      | 0.75         |
+ *
+ * @example
+ * ```ts
+ * kubesenseSdk.init({
+ *   // ...
+ *   sessionReplayCanvasRecording: {
+ *     enable: true,
+ *     quality: CanvasRecordingQuality.MEDIUM,
+ *   },
+ * })
+ * ```
+ */
+export const CanvasRecordingQuality = {
+  LOW: 'low',
+  MEDIUM: 'medium',
+  HIGH: 'high',
+} as const
+export type CanvasRecordingQuality = (typeof CanvasRecordingQuality)[keyof typeof CanvasRecordingQuality]
+
+/**
+ * The resolved canvas recording tuning behind each {@link CanvasRecordingQuality} preset.
+ */
+export interface CanvasRecordingConfiguration {
+  enable: true
+  maxFramesPerSecond: number
+  hashingMaxDimension: number
+  maxImageDimension: number
+  encodeQuality: number
+}
+
+const CANVAS_RECORDING_QUALITY_PRESETS: Record<CanvasRecordingQuality, Omit<CanvasRecordingConfiguration, 'enable'>> = {
+  [CanvasRecordingQuality.LOW]: {
+    maxFramesPerSecond: 1,
+    hashingMaxDimension: 50,
+    maxImageDimension: 600,
+    encodeQuality: 0.3,
+  },
+  [CanvasRecordingQuality.MEDIUM]: {
+    maxFramesPerSecond: 4,
+    hashingMaxDimension: 100,
+    maxImageDimension: 1000,
+    encodeQuality: 0.5,
+  },
+  [CanvasRecordingQuality.HIGH]: {
+    maxFramesPerSecond: 8,
+    hashingMaxDimension: 100,
+    maxImageDimension: 1280,
+    encodeQuality: 0.75,
+  },
+}
+
+/**
+ * Upstream gates canvas recording behind the `session_replay_record_canvas` experimental flag; in
+ * this SDK it is a regular option. The preset's values can be overridden one by one, which is how the
+ * dashboard's remote configuration tunes them.
+ */
+function resolveCanvasRecordingConfiguration(
+  configuration:
+    | {
+        enable: boolean
+        quality: CanvasRecordingQuality
+        maxFramesPerSecond?: number
+        maxImageDimension?: number
+        hashingMaxDimension?: number
+      }
+    | undefined
+): CanvasRecordingConfiguration | undefined {
+  const preset = configuration && CANVAS_RECORDING_QUALITY_PRESETS[configuration.quality]
+  if (!configuration?.enable || !preset) {
+    return undefined
+  }
+
+  return {
+    enable: true,
+    ...preset,
+    maxFramesPerSecond: configuration.maxFramesPerSecond ?? preset.maxFramesPerSecond,
+    maxImageDimension: configuration.maxImageDimension ?? preset.maxImageDimension,
+    hashingMaxDimension: configuration.hashingMaxDimension ?? preset.hashingMaxDimension,
+  }
+}
 
 export type FeatureFlagsForEvents = 'vital' | 'action' | 'long_task' | 'resource'
 
+/**
+ * Function called before a RUM event is sent to KubeSense. See {@link RumInitConfiguration.beforeSend}
+ *
+ * @param event - The RUM event
+ * @param context - The RUM event domain context providing access to native browser data based on the event type (e.g. error, performance entry).
+ * @returns true if the event should be sent to KubeSense, false otherwise
+ */
+export type RumBeforeSend = (event: RumEvent, context: RumEventDomainContext) => boolean
+
 export interface GraphQlUrlOption {
   match: MatchOption
   trackPayload?: boolean
   trackResponseErrors?: boolean
 }
 
-export interface RumConfiguration extends Configuration {
-  // Built from init configuration
-  actionNameAttribute: string | undefined
-  traceSampleRate: number
-  rulePsr: number | undefined
+export interface MatchHeader {
+  url?: MatchOption
+  name?: MatchOption
+  extractor?: RegExp
+  location?: 'request' | 'response' | 'any'
+}
+
+export const RUM_SCHEMA = {
+  ...BROWSER_CORE_SCHEMA,
+
+  // Required
+  applicationId: { type: 'string', required: true },
+
+  // Optional strings
+  actionNameAttribute: { type: 'string' },
+  workerUrl: { type: 'string' },
+  subdomain: { type: 'string' },
+
+  // Sample rates
+  sessionReplaySampleRate: { type: 'percentage', default: 0 },
+  traceSampleRate: { type: 'percentage', default: 100 },
+  profilingSampleRate: { type: 'percentage', default: 0 },
+
+  // Booleans
+  compressIntakeRequests: { type: 'boolean', default: false },
+  trackUserInteractions: { type: 'boolean', default: true, strict: false },
+  trackResources: { type: 'boolean', default: true, strict: false },
+  trackLongTasks: { type: 'boolean', default: true, strict: false },
+  trackViewsManually: { type: 'boolean', default: false, strict: false },
+  betaEnableViewUpdates: { type: 'boolean' },
+  betaTrackWebSockets: { type: 'boolean', default: false, strict: false },
+  enablePrivacyForActionName: { type: 'boolean', default: true },
+  propagateTraceBaggage: { type: 'boolean', default: true },
+  startSessionReplayRecordingManually: { type: 'boolean', default: false, strict: false },
+  enableRemoteSdkConfiguration: { type: 'boolean', default: false, strict: false },
+  // KubeSense extensions
+  firstPartyDomains: { type: 'match-option', multiple: true, default: [] as MatchOption[] },
+  sessionReplayRoutes: {
+    type: 'schema',
+    strict: false,
+    schema: {
+      // Not strict: an unusable entry is dropped rather than failing the whole configuration, so a
+      // typo in one route does not take Session Replay down entirely.
+      include: { type: 'match-option', multiple: true, strict: false },
+      exclude: { type: 'match-option', multiple: true, strict: false },
+    },
+  },
+
+  sessionReplayCanvasRecording: {
+    type: 'schema',
+    schema: {
+      enable: { type: 'boolean', required: true },
+      quality: { type: 'enum', values: CanvasRecordingQuality, default: CanvasRecordingQuality.MEDIUM },
+      maxFramesPerSecond: { type: 'number', min: 0, max: 8 },
+      maxImageDimension: { type: 'number', min: 1, max: 1280 },
+      hashingMaxDimension: { type: 'number', min: 1, max: 100 },
+    },
+  },
+
+  // Enums
+  defaultPrivacyLevel: {
+    type: 'enum',
+    values: DefaultPrivacyLevel,
+    default: DefaultPrivacyLevel.MASK_USER_INPUT,
+    strict: false,
+  },
+  traceContextInjection: {
+    type: 'enum',
+    values: TraceContextInjection,
+    default: TraceContextInjection.SAMPLED,
+    strict: false,
+  },
+
+  // Arrays
+  excludedActivityUrls: { type: 'match-option', multiple: true, default: [] as MatchOption[] },
+  allowedTracingUrls: {
+    type: 'union',
+    multiple: true,
+    strict: false,
+    default: [] as Array<MatchOption | { match: MatchOption; propagatorTypes: PropagatorType[] }>,
+    variants: [
+      { type: 'match-option' },
+      {
+        type: 'schema',
+        schema: {
+          match: { type: 'match-option', required: true },
+          propagatorTypes: {
+            type: 'enum',
+            values: ['kubesense', 'b3', 'b3multi', 'tracecontext'] as const,
+            multiple: true,
+            strict: false,
+            default: DEFAULT_PROPAGATOR_TYPES,
+          },
+        },
+      },
+    ],
+  },
+  plugins: {
+    type: 'schema',
+    multiple: true,
+    strict: false,
+    default: [] as RumPlugin[],
+    schema: {
+      name: { type: 'string', required: true },
+      getConfigurationTelemetry: {
+        type: 'function',
+        strict: false,
+        signature: undefined as RumPlugin['getConfigurationTelemetry'],
+      },
+      onInit: { type: 'function', strict: false, signature: undefined as RumPlugin['onInit'] },
+      onRumStart: { type: 'function', strict: false, signature: undefined as RumPlugin['onRumStart'] },
+    },
+  },
+  trackFeatureFlagsForEvents: {
+    type: 'enum',
+    values: ['vital', 'action', 'long_task', 'resource'] as const,
+    multiple: true,
+    strict: false,
+    default: [] as FeatureFlagsForEvents[],
+  },
+} as const
+
+export type RumConfiguration = Omit<
+  InferredConfig<typeof RUM_SCHEMA>,
+  'allowedTracingUrls' | 'sessionReplayCanvasRecording'
+> & {
   allowedTracingUrls: TracingOption[]
-  excludedActivityUrls: MatchOption[]
-  workerUrl: string | undefined
-  compressIntakeRequests: boolean
-  applicationId: string
-  defaultPrivacyLevel: DefaultPrivacyLevel
-  enablePrivacyForActionName: boolean
-  sessionReplaySampleRate: number
-  startSessionReplayRecordingManually: boolean
-  sessionReplayRoutes: SessionReplayRoutes | undefined
-  trackUserInteractions: boolean
-  trackViewsManually: boolean
-  trackResources: boolean
-  trackLongTasks: boolean
-  trackBfcacheViews: boolean
-  trackEarlyRequests: boolean
-  subdomain?: string
-  traceContextInjection: TraceContextInjection
-  plugins: RumPlugin[]
-  trackFeatureFlagsForEvents: FeatureFlagsForEvents[]
-  profilingSampleRate: number
-  propagateTraceBaggage: boolean
+  betaEnableViewUpdates: boolean
+  rulePsr: number | undefined
+  trackResourceHeaders: MatchHeader[]
   allowedGraphQlUrls: GraphQlUrlOption[]
-  firstPartyDomains: MatchOption[]
+  remoteConfigurationId: string | undefined
+  sessionReplayCanvasRecording: CanvasRecordingConfiguration | undefined
 }
 
-export function validateAndBuildRumConfiguration(
-  initConfiguration: RumInitConfiguration,
-  errorStack?: string
-): RumConfiguration | undefined {
-  if (
-    initConfiguration.trackFeatureFlagsForEvents !== undefined &&
-    !Array.isArray(initConfiguration.trackFeatureFlagsForEvents)
-  ) {
-    display.warn('trackFeatureFlagsForEvents should be an array')
-  }
-
-  if (!initConfiguration.applicationId) {
-    display.error('Application ID is not configured, no RUM data will be collected.')
-    return
+/**
+ * Resolves whether partial view updates are enabled. Never enabled when the event bridge is used.
+ * Otherwise an explicit `betaEnableViewUpdates` takes precedence, and it defaults to true for CDN
+ * users that do not go through a proxy: a proxy may not forward the `view_update` event type yet,
+ * and npm users pin an SDK version so they opt in explicitly.
+ *
+ * The CDN check is temporary, the next step is to default this to true unless `proxy` is set.
+ * TODO next major: remove the option.
+ */
+function isViewUpdatesEnabled(
+  explicit: boolean | undefined,
+  proxy: InitConfiguration['proxy'],
+  sdkName: SdkName | undefined
+): boolean {
+  if (canUseEventBridge()) {
+    // The bridge replaces the batch transport, and `view_update` events are only created by the
+    // batch dispatcher, so partial updates never happen in a WebView. Ignore the explicit value
+    // too, otherwise telemetry reports updates that cannot be sent.
+    return false
   }
 
-  if (
-    !isSampleRate(initConfiguration.sessionReplaySampleRate, 'Session Replay') ||
-    !isSampleRate(initConfiguration.traceSampleRate, 'Trace')
-  ) {
-    return
-  }
+  // The Salesforce bundle is a CDN build, but the supported install flow uploads it as a static
+  // resource, so publishing a new bundle does not roll those deployments back. Keep them out of
+  // the default, they can still opt in explicitly.
+  return explicit ?? (__BUILD_ENV__SDK_SETUP__ === 'cdn' && !proxy && sdkName !== 'rum-salesforce')
+}
 
-  if (initConfiguration.excludedActivityUrls !== undefined && !Array.isArray(initConfiguration.excludedActivityUrls)) {
-    display.error('Excluded Activity Urls should be an array')
-    return
-  }
+export function validateAndBuildRumConfiguration(
+  initConfiguration: RumInitConfiguration,
+  sdkName?: SdkName
+): RumConfiguration | undefined {
+  const config = validateAndBuildConfiguration(
+    initConfiguration as unknown as Record<string, unknown>,
+    RUM_SCHEMA,
+    display
+  )
 
-  const allowedTracingUrls = validateAndBuildTracingOptions(initConfiguration)
-  if (!allowedTracingUrls) {
+  if (!config) {
     return
   }
 
-  const baseConfiguration = validateAndBuildConfiguration(initConfiguration, errorStack)
-
-  const allowedGraphQlUrls = validateAndBuildGraphQlOptions(initConfiguration)
+  const allowedTracingUrls = config.allowedTracingUrls.map(normalizeTracingOption).filter(Boolean) as TracingOption[]
 
-  if (!baseConfiguration) {
+  if (allowedTracingUrls.length > 0 && !config.service) {
+    display.error('Service needs to be configured when tracing is enabled')
     return
   }
 
-  const sessionReplaySampleRate = initConfiguration.sessionReplaySampleRate ?? 0
+  const sessionReplayCanvasRecording = resolveCanvasRecordingConfiguration(config.sessionReplayCanvasRecording)
 
   return {
-    applicationId: initConfiguration.applicationId,
-    actionNameAttribute: initConfiguration.actionNameAttribute,
-    sessionReplaySampleRate,
-    startSessionReplayRecordingManually:
-      initConfiguration.startSessionReplayRecordingManually !== undefined
-        ? !!initConfiguration.startSessionReplayRecordingManually
-        : sessionReplaySampleRate === 0,
-    sessionReplayRoutes: validateSessionReplayRoutes(initConfiguration.sessionReplayRoutes),
-    traceSampleRate: initConfiguration.traceSampleRate ?? 100,
-    rulePsr: isNumber(initConfiguration.traceSampleRate) ? initConfiguration.traceSampleRate / 100 : undefined,
+    ...config,
+    service: config.service || config.applicationId,
+    sessionReplayCanvasRecording,
+    betaEnableViewUpdates: isViewUpdatesEnabled(config.betaEnableViewUpdates, config.proxy, sdkName),
     allowedTracingUrls,
-    excludedActivityUrls: initConfiguration.excludedActivityUrls ?? [],
-    workerUrl: initConfiguration.workerUrl,
-    compressIntakeRequests: !!initConfiguration.compressIntakeRequests,
-    trackUserInteractions: !!(initConfiguration.trackUserInteractions ?? true),
-    trackViewsManually: !!initConfiguration.trackViewsManually,
-    trackResources: !!(initConfiguration.trackResources ?? true),
-    trackLongTasks: !!(initConfiguration.trackLongTasks ?? true),
-    trackBfcacheViews: !!initConfiguration.trackBfcacheViews,
-    trackEarlyRequests: !!initConfiguration.trackEarlyRequests,
-    subdomain: initConfiguration.subdomain,
-    defaultPrivacyLevel: objectHasValue(DefaultPrivacyLevel, initConfiguration.defaultPrivacyLevel)
-      ? initConfiguration.defaultPrivacyLevel
-      : DefaultPrivacyLevel.MASK,
-    enablePrivacyForActionName: !!initConfiguration.enablePrivacyForActionName,
-    traceContextInjection: objectHasValue(TraceContextInjection, initConfiguration.traceContextInjection)
-      ? initConfiguration.traceContextInjection
-      : TraceContextInjection.SAMPLED,
-    plugins: initConfiguration.plugins || [],
-    trackFeatureFlagsForEvents: initConfiguration.trackFeatureFlagsForEvents || [],
-    profilingSampleRate: initConfiguration.profilingSampleRate ?? 0,
-    propagateTraceBaggage: !!initConfiguration.propagateTraceBaggage,
-    allowedGraphQlUrls,
-    firstPartyDomains: initConfiguration.firstPartyDomains ?? [],
-    ...baseConfiguration,
-  }
-}
-
-/**
- * Validates allowedTracingUrls and converts match options to tracing options
- */
-function validateAndBuildTracingOptions(initConfiguration: RumInitConfiguration): TracingOption[] | undefined {
-  if (initConfiguration.allowedTracingUrls === undefined) {
-    return []
-  }
-  if (!Array.isArray(initConfiguration.allowedTracingUrls)) {
-    display.error('Allowed Tracing URLs should be an array')
-    return
-  }
-  if (initConfiguration.allowedTracingUrls.length !== 0 && initConfiguration.service === undefined) {
-    display.error('Service needs to be configured when tracing is enabled')
-    return
+    beforeSend: config.beforeSend
+      ? (catchUserErrors(config.beforeSend, 'beforeSend threw an error:') as typeof config.beforeSend)
+      : undefined,
+    rulePsr: isNumber(initConfiguration.traceSampleRate) ? initConfiguration.traceSampleRate / 100 : undefined,
+    trackResourceHeaders: validateAndBuildTrackResourceHeaders(initConfiguration),
+    allowedGraphQlUrls: validateAndBuildGraphQlOptions(initConfiguration),
+    remoteConfigurationId: getRemoteConfigurationId(initConfiguration),
   }
-  // Convert from (MatchOption | TracingOption) to TracingOption, remove unknown properties
-  const tracingOptions: TracingOption[] = []
-  initConfiguration.allowedTracingUrls.forEach((option) => {
-    if (isMatchOption(option)) {
-      tracingOptions.push({ match: option, propagatorTypes: DEFAULT_PROPAGATOR_TYPES })
-    } else if (isTracingOption(option)) {
-      tracingOptions.push(option)
-    } else {
-      display.warn(
-        'Allowed Tracing Urls parameters should be a string, RegExp, function, or an object. Ignoring parameter',
-        option
-      )
-    }
-  })
-
-  return tracingOptions
 }
 
 /**
@@ -478,18 +769,32 @@ function getSelectedTracingPropagators(configuration: RumInitConfiguration): Pro
 
   if (isNonEmptyArray(configuration.allowedTracingUrls)) {
     configuration.allowedTracingUrls.forEach((option) => {
-      if (isMatchOption(option)) {
-        DEFAULT_PROPAGATOR_TYPES.forEach((propagatorType) => usedTracingPropagators.add(propagatorType))
-      } else if (getType(option) === 'object' && Array.isArray(option.propagatorTypes)) {
-        // Ensure we have an array, as we cannot rely on types yet (configuration is provided by users)
-        option.propagatorTypes.forEach((propagatorType) => usedTracingPropagators.add(propagatorType))
-      }
+      normalizeTracingOption(option)?.propagatorTypes.forEach((propagatorType) =>
+        usedTracingPropagators.add(propagatorType)
+      )
     })
   }
 
   return Array.from(usedTracingPropagators)
 }
 
+function normalizeTracingOption(option: unknown): TracingOption | undefined {
+  if (isMatchOption(option)) {
+    return { match: option, propagatorTypes: DEFAULT_PROPAGATOR_TYPES }
+  }
+
+  if (
+    isIndexableObject(option) &&
+    isMatchOption(option.match) &&
+    (option.propagatorTypes === null || option.propagatorTypes === undefined || Array.isArray(option.propagatorTypes))
+  ) {
+    return {
+      match: option.match,
+      propagatorTypes: option.propagatorTypes || DEFAULT_PROPAGATOR_TYPES,
+    }
+  }
+}
+
 /**
  * Build GraphQL options from configuration
  */
@@ -508,7 +813,7 @@ function validateAndBuildGraphQlOptions(initConfiguration: RumInitConfiguration)
   initConfiguration.allowedGraphQlUrls.forEach((option) => {
     if (isMatchOption(option)) {
       graphQlOptions.push({ match: option, trackPayload: false, trackResponseErrors: false })
-    } else if (option && typeof option === 'object' && 'match' in option && isMatchOption(option.match)) {
+    } else if (isIndexableObject(option) && isMatchOption(option.match)) {
       graphQlOptions.push({
         match: option.match,
         trackPayload: !!option.trackPayload,
@@ -520,33 +825,99 @@ function validateAndBuildGraphQlOptions(initConfiguration: RumInitConfiguration)
   return graphQlOptions
 }
 
+const VALID_HEADER_LOCATIONS = ['request', 'response', 'any']
+
+function validateAndBuildTrackResourceHeaders(initConfiguration: RumInitConfiguration): MatchHeader[] {
+  const option = initConfiguration.trackResourceHeaders
+
+  if (option === undefined || option === false) {
+    return []
+  }
+
+  if (option === true) {
+    return DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name }))
+  }
+
+  if (!Array.isArray(option)) {
+    display.warn('trackResourceHeaders should be true or an array of MatchHeader')
+    return []
+  }
+
+  if (option.length === 0) {
+    display.warn('trackResourceHeaders is an empty array, no headers will be captured')
+    return []
+  }
+
+  const result: MatchHeader[] = []
+
+  option.forEach((item, index) => {
+    if (!isIndexableObject(item)) {
+      display.warn(`trackResourceHeaders[${index}] should be a MatchHeader object`)
+      return
+    }
+    if (item.name !== undefined && !isMatchOption(item.name)) {
+      display.warn(`trackResourceHeaders[${index}].name should be a MatchOption`)
+      return
+    }
+    if (item.url !== undefined && !isMatchOption(item.url)) {
+      display.warn(`trackResourceHeaders[${index}].url should be a MatchOption`)
+      return
+    }
+    if (item.extractor !== undefined && !(item.extractor instanceof RegExp)) {
+      display.warn(`trackResourceHeaders[${index}].extractor should be a RegExp`)
+      return
+    }
+    if (
+      item.location !== undefined &&
+      (typeof item.location !== 'string' || !VALID_HEADER_LOCATIONS.includes(item.location))
+    ) {
+      display.warn(`trackResourceHeaders[${index}].location should be 'request', 'response', or 'any'`)
+      return
+    }
+
+    const { name, ...rest } = item
+    result.push({
+      ...rest,
+      ...(name !== undefined ? { name: typeof name === 'string' ? name.toLowerCase() : name } : {}),
+    })
+  })
+
+  return result
+}
+
 function hasGraphQlPayloadTracking(allowedGraphQlUrls: RumInitConfiguration['allowedGraphQlUrls']): boolean {
   return (
     isNonEmptyArray(allowedGraphQlUrls) &&
-    allowedGraphQlUrls.some((option) => {
-      if (typeof option === 'object' && 'trackPayload' in option) {
-        return !!option.trackPayload
-      }
-      return false
-    })
+    allowedGraphQlUrls.some((option) => isIndexableObject(option) && option.trackPayload)
   )
 }
 
 function hasGraphQlResponseErrorsTracking(allowedGraphQlUrls: RumInitConfiguration['allowedGraphQlUrls']): boolean {
   return (
     isNonEmptyArray(allowedGraphQlUrls) &&
-    allowedGraphQlUrls.some((option) => {
-      if (typeof option === 'object' && 'trackResponseErrors' in option) {
-        return !!option.trackResponseErrors
-      }
-      return false
-    })
+    allowedGraphQlUrls.some((option) => isIndexableObject(option) && option.trackResponseErrors)
   )
 }
 
-export function serializeRumConfiguration(configuration: RumInitConfiguration) {
+function getTrackResourceHeadersTelemetryValue(
+  trackResourceHeaders: RumInitConfiguration['trackResourceHeaders']
+): 'default_headers' | 'custom' | undefined {
+  if (trackResourceHeaders === true) {
+    return 'default_headers'
+  }
+  if (Array.isArray(trackResourceHeaders)) {
+    return 'custom'
+  }
+}
+
+export function serializeRumConfiguration(
+  configuration: RumInitConfiguration,
+  sdkName?: SdkName,
+  remoteConfigurationMetadata?: RemoteConfigurationMetadata
+) {
   const baseSerializedConfiguration = serializeConfiguration(configuration)
 
+  // `use_` prefix is for telemetry options that track usage of a configuration option as a boolean to avoid capturing customer data
   return {
     session_replay_sample_rate: configuration.sessionReplaySampleRate,
     start_session_replay_recording_manually: configuration.startSessionReplayRecordingManually,
@@ -568,24 +939,32 @@ export function serializeRumConfiguration(configuration: RumInitConfiguration) {
     track_user_interactions: configuration.trackUserInteractions,
     track_resources: configuration.trackResources,
     track_long_task: configuration.trackLongTasks,
-    track_bfcache_views: configuration.trackBfcacheViews,
-    track_early_requests: configuration.trackEarlyRequests,
     plugins: configuration.plugins?.map((plugin) => ({
       name: plugin.name,
       ...plugin.getConfigurationTelemetry?.(),
     })),
     track_feature_flags_for_events: configuration.trackFeatureFlagsForEvents,
-    remote_configuration_id: configuration.remoteConfigurationId,
+    remote_configuration_id: getRemoteConfigurationId(configuration),
+    remote_configuration: remoteConfigurationMetadata && {
+      last_modified: remoteConfigurationMetadata.lastModified,
+      last_synced: remoteConfigurationMetadata.lastSynced,
+      first_applied: remoteConfigurationMetadata.firstApplied,
+      sync_id: remoteConfigurationMetadata.syncId,
+    },
     profiling_sample_rate: configuration.profilingSampleRate,
     use_remote_configuration_proxy: !!configuration.remoteConfigurationProxy,
-    // Kubesense extensions: whether the dashboard-managed remote document is
-    // in play, and whether replay recording is route-scoped — both needed to
-    // interpret the reported values on the dashboard side.
+    // KubeSense extensions: whether the dashboard-managed remote document is in play, whether
+    // replay recording is route-scoped, and whether resource classification has an explicit
+    // first-party list — all needed to interpret the reported values on the dashboard side.
     enable_remote_sdk_configuration: !!configuration.enableRemoteSdkConfiguration,
     use_session_replay_routes:
       !!configuration.sessionReplayRoutes &&
       (isNonEmptyArray(configuration.sessionReplayRoutes.include) ||
         isNonEmptyArray(configuration.sessionReplayRoutes.exclude)),
+    use_first_party_domains: isNonEmptyArray(configuration.firstPartyDomains),
+    track_resource_headers: getTrackResourceHeadersTelemetryValue(configuration.trackResourceHeaders),
+    beta_enable_view_updates: isViewUpdatesEnabled(configuration.betaEnableViewUpdates, configuration.proxy, sdkName),
+    beta_track_web_sockets: configuration.betaTrackWebSockets,
     ...baseSerializedConfiguration,
   } satisfies RawTelemetryConfiguration
 }