@amplitude/session-replay-browser 1.46.0 → 1.47.0-sr-trc-debug-log.1

package/lib/cjs/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/config/types.ts"],"names":[],"mappings":";;;AAwDa,QAAA,kBAAkB,GAAG,QAAQ,CAAC","sourcesContent":["import { IConfig, LogLevel, ILogger } from '@amplitude/analytics-core';\nimport { StoreType, ConsoleLogLevel } from '../typings/session-replay';\nimport { TargetingFlag } from '@amplitude/targeting';\n\nexport interface SamplingConfig {\n  sample_rate: number;\n  capture_enabled: boolean;\n  min_session_duration_ms?: number;\n}\n\nexport interface InteractionConfig {\n  trackEveryNms?: number;\n  enabled: boolean; // defaults to false\n  batch: boolean; // defaults to false\n  /**\n   * UGC filter rules.\n   */\n  ugcFilterRules?: UGCFilterRule[];\n}\n\nexport interface LoggingConfig {\n  console: {\n    enabled: boolean;\n    levels: ConsoleLogLevel[];\n  };\n  network?: {\n    enabled: boolean;\n    body?: {\n      request?: boolean;\n      response?: boolean;\n      maxBodySizeBytes?: number;\n    };\n  };\n}\n\nexport type TargetingConfig = TargetingFlag;\n\nexport type SessionReplayRemoteConfig = {\n  sr_sampling_config?: SamplingConfig;\n  sr_privacy_config?: PrivacyConfig;\n  sr_interaction_config?: InteractionConfig;\n  sr_logging_config?: LoggingConfig;\n  sr_targeting_config?: TargetingConfig;\n};\n\nexport interface SessionReplayRemoteConfigAPIResponse {\n  configs: {\n    sessionReplay: SessionReplayRemoteConfig;\n  };\n}\n\nexport type MaskLevel =\n  | 'light' // only mask a subset of inputs that's deemed sensitive - password, credit card, telephone #, email. These are information we never want to capture.\n  | 'medium' // mask all form fields (inputs); page text is captured as-is\n  | 'conservative'; // mask all inputs and all texts\n\nexport const DEFAULT_MASK_LEVEL = 'medium';\n\n// err on the side of excluding more\nexport type PrivacyConfig = {\n  blockSelector?: string | string[]; // exclude in the UI\n  defaultMaskLevel?: MaskLevel;\n  maskSelector?: string[];\n  unmaskSelector?: string[];\n  maskAttributes?: string[]; // HTML attribute names to mask (e.g. [\"placeholder\", \"aria-label\"])\n  /**\n   * Per-URL overrides for `defaultMaskLevel`. Each entry contains a glob pattern (`match`)\n   * and a `maskLevel` to apply when the current page URL matches that pattern.\n   * Rules are evaluated in order; the first match wins. Remote rules take precedence\n   * over local rules (remote entries are prepended before local entries).\n   *\n   * @example\n   * urlMaskLevels: [\n   *   { match: 'https://example.com/checkout/*', maskLevel: 'conservative' },\n   *   { match: 'https://example.com/public/*',   maskLevel: 'light' },\n   * ]\n   */\n  urlMaskLevels?: Array<{ match: string; maskLevel: MaskLevel }>;\n};\n\n/**\n * UGC filter rule.\n */\nexport type UGCFilterRule = {\n  /**\n   * The selector of the UGC element.\n   */\n  selector: string;\n  /**\n   * The replacement text for the UGC element.\n   */\n  replacement: string;\n};\n\nexport interface CrossOriginIframesConfig {\n  enabled: boolean;\n  /**\n   * When true (default), the parent SDK sends start/stop signals to child iframes via\n   * postMessage, keeping their recording lifecycle in sync with the parent.\n   *\n   * **Privacy note:** The child page's rrweb instance performs its own DOM serialization,\n   * so the parent's privacy config (mask levels, block selectors) does NOT automatically\n   * apply inside the iframe. Privacy settings must be configured independently on the child page.\n   *\n   * **Third-party iframes:** Cannot capture iframes you don't control (e.g. Stripe, Google\n   * Maps) — both parent and child pages must load the SDK with `crossOriginIframes.enabled: true`.\n   *\n   * Set to `false` to skip coordination and manage the child recording lifecycle yourself.\n   * @defaultValue true\n   */\n  coordinateChildren?: boolean;\n}\n\nexport interface SessionReplayLocalConfig extends IConfig {\n  apiKey: string;\n  loggerProvider: ILogger;\n  /**\n   * LogLevel.None or LogLevel.Error or LogLevel.Warn or LogLevel.Verbose or LogLevel.Debug.\n   * Sets the log level.\n   *\n   * @defaultValue LogLevel.Warn\n   */\n  logLevel: LogLevel;\n  /**\n   * The maximum number of retries allowed for sending replay events.\n   * Once this limit is reached, failed events will no longer be sent.\n   *\n   * @defaultValue 2\n   */\n  flushMaxRetries: number;\n  /**\n   * Use this option to control how many sessions to select for replay collection.\n   * The number should be a decimal between 0 and 1, for example 0.4, representing\n   * the fraction of sessions to have randomly selected for replay collection.\n   * Over a large number of sessions, 0.4 would select 40% of those sessions.\n   * Sample rates as small as six decimal places (0.000001) are supported.\n   *\n   * @defaultValue 0\n   */\n  sampleRate: number;\n  privacyConfig?: PrivacyConfig;\n  /**\n   * Adds additional debug event property to help debug instrumentation issues\n   * (such as mismatching apps). Only recommended for debugging initial setup,\n   * and not recommended for production.\n   */\n  debugMode?: boolean;\n  /**\n   * Specifies the endpoint URL to fetch remote configuration.\n   * If provided, it overrides the default server zone configuration.\n   */\n  configServerUrl?: string;\n  /**\n   * Specifies the endpoint URL for sending session replay data.\n   * If provided, it overrides the default server zone configuration.\n   */\n  trackServerUrl?: string;\n  /**\n   * If stylesheets are inlined, the contents of the stylesheet will be stored.\n   * During replay, the stored stylesheet will be used instead of attempting to fetch it remotely.\n   * This prevents replays from appearing broken due to missing stylesheets.\n   * Note: Inlining stylesheets may not work in all cases.\n   */\n  shouldInlineStylesheet?: boolean;\n  version?: SessionReplayVersion;\n  /**\n   * Performance configuration config. If enabled, we will defer compression\n   * to be done during the browser's idle periods.\n   */\n  performanceConfig?: SessionReplayPerformanceConfig;\n  /**\n   * Specifies how replay events should be stored. `idb` uses IndexedDB to persist replay events\n   * when all events cannot be sent during capture. `memory` stores replay events only in memory,\n   * meaning events are lost when the page is closed. If IndexedDB is unavailable, the system falls back to `memory`.\n   *\n   * @defaultValue 'memory' — reflects the validated amp-on-amp perf config (SR-4646). `memory`\n   * drops cross-navigation persistence (unsent events do not survive a full page reload), which\n   * is the intended trade-off for lower IDB overhead.\n   */\n  storeType: StoreType;\n\n  /**\n   * If true, the SDK will compress replay events using a web worker.\n   * This offloads compression to a separate thread, improving performance on the main thread.\n   * Set to `false` to keep compression on the main thread.\n   *\n   * @defaultValue true — reflects the validated amp-on-amp perf config (SR-4646). Was `false`\n   * prior to that change.\n   */\n  useWebWorker?: boolean;\n\n  /**\n   * Controls transport-layer gzip compression of session replay request bodies.\n   * When true (default), the SDK gzip-compresses the JSON request body via the browser's\n   * `CompressionStream` API and sets `Content-Encoding: gzip` on the POST. When false,\n   * the SDK sends the raw JSON body with no `Content-Encoding` header.\n   *\n   * Disabling is intended as a debugging / safety opt-out (e.g. for diagnosing\n   * server-side decompression issues); it increases egress bytes and is not\n   * recommended for production.\n   *\n   * Note: This is independent of `useWebWorker` / `performanceConfig`, which control\n   * per-event rrweb compression that runs before events are queued.\n   *\n   * @defaultValue true\n   */\n  enableTransportCompression?: boolean;\n\n  /**\n   * Milliseconds to wait for a send request before aborting it. `fetch()` has no native\n   * timeout, so a request stuck \"pending\" would block the serial flush loop indefinitely;\n   * the SDK aborts after this many ms and routes the abort as a retryable failure.\n   *\n   * Set to `0` (or a negative value) to disable the timeout entirely — note this\n   * reintroduces the head-of-line-blocking risk a wedged request can cause, so it is\n   * intended only as a diagnostic/experiment opt-out.\n   *\n   * Tuning this higher is useful when large, slow-but-succeeding uploads are being aborted\n   * at the default and counted as failures (which also triggers a retry, inflating request\n   * volume / throttle pressure).\n   *\n   * @defaultValue 10000\n   */\n  sendTimeoutMs?: number;\n\n  userProperties?: { [key: string]: any };\n\n  /**\n   * If true, applies a background color to blocked elements in the replay.\n   * This helps visualize which elements are blocked from being captured.\n   */\n  applyBackgroundColorToBlockedElements?: boolean;\n  /**\n   * Enables URL change polling as a fallback for SPA route tracking.\n   * When enabled, the SDK will periodically check for URL changes every second\n   * in addition to patching the History API. This is useful for edge cases where\n   * route changes might bypass the standard History API methods.\n   *\n   * @defaultValue false\n   */\n  enableUrlChangePolling?: boolean;\n  /**\n   * Specifies the interval in milliseconds for URL change polling when enableUrlChangePolling is true.\n   * The SDK will check for URL changes at this interval as a fallback for SPA route tracking.\n   *\n   * @defaultValue 1000\n   */\n  urlChangePollingInterval?: number;\n  /**\n   * Whether to capture document title in URL change events.\n   * When disabled, the title field will be empty in URL change events.\n   *\n   * @defaultValue false\n   */\n  captureDocumentTitle?: boolean;\n  interactionConfig?: InteractionConfig;\n  /**\n   * When true (default), the CSS rules of any `adoptedStyleSheets` on shadow roots and\n   * the document are serialized **inline** within the full snapshot. This makes the snapshot\n   * self-contained so that shadow DOM styles are replayed correctly even if subsequent\n   * incremental `AdoptedStyleSheet` events are dropped in transit.\n   *\n   * Set to `false` to revert to the legacy behavior where adopted stylesheet rules are\n   * emitted as separate incremental events (which may be lost if delivery is unreliable).\n   * Only consider opting out if snapshot payload size is a critical concern.\n   *\n   * @defaultValue true\n   */\n  captureAdoptedStyleSheets?: boolean;\n  /**\n   * Enables recording of cross-origin iframes. Both the parent page and each child iframe\n   * page must load the Amplitude Session Replay SDK with this option enabled.\n   *\n   * When enabled, rrweb uses `postMessage` to relay child DOM events to the parent, which\n   * merges them into a single unified event stream.\n   */\n  crossOriginIframes?: CrossOriginIframesConfig;\n  /** Interval in ms at which the SDK takes a full DOM snapshot. Disabled by default — periodic snapshots are expensive. Recommended value: 300000 (5 min). */\n  fullSnapshotIntervalMs?: number;\n  /**\n   * Controls how often the SDK splits buffered rrweb events into a sequence and dispatches\n   * the resulting batch to the server. The interval starts at `minIntervalMs` and grows by\n   * `minIntervalMs` after each split, capped at `maxIntervalMs`. Lowering values increases\n   * replay availability latency improvements at the cost of more requests; raising them\n   * reduces request volume (and 200+`X-Session-Replay-Event-Skipped` throttling responses)\n   * at the cost of slightly delayed replay availability.\n   *\n   * Defaults to `{ minIntervalMs: 1000, maxIntervalMs: 10_000 }`, reflecting the validated\n   * amp-on-amp perf config (SR-4646); the `minIntervalMs` default was `500` prior to that\n   * change. Tune up if the server is back-pressuring the SDK on session start.\n   */\n  flushIntervalConfig?: FlushIntervalConfig;\n  /**\n   * When true, every rrweb full snapshot is flushed to the server immediately so replays\n   * become playable as early as possible. When false (default), full-snapshot sends are\n   * deferred to the normal interval/size flush cadence instead. The snapshot is still\n   * compressed and buffered immediately either way (ordering and page-exit beacon coverage\n   * are preserved); only the eager network send is suppressed. The default-off behavior\n   * reduces request volume for pages that produce many full snapshots (e.g. focus-driven or\n   * `fullSnapshotIntervalMs` checkouts), especially when many SDK instances run on the same\n   * page.\n   *\n   * @defaultValue false — reflects the validated amp-on-amp perf config (SR-4646). Was `true`\n   * prior to that change.\n   */\n  eagerFullSnapshotSend?: boolean;\n  /**\n   * When true, the window `focus` listener forces a fresh rrweb full snapshot\n   * (`takeFullSnapshot`) every time the page regains focus, so the replay reflects any DOM\n   * changes that happened while the tab was backgrounded. When false (default), the on-focus\n   * full snapshot is skipped entirely (recording simply continues from the existing stream).\n   *\n   * On pages with heavy focus churn (e.g. embedded iframes, inline editors that repeatedly\n   * steal and return focus) this fires constantly, and when combined with\n   * `eagerFullSnapshotSend` each focus produces an immediate network send — the primary\n   * driver of focus-driven request storms. The default-off behavior removes the snapshot (and\n   * therefore the send) at the cost of slightly staler post-focus frames.\n   *\n   * @defaultValue false — reflects the validated amp-on-amp perf config (SR-4646). Was `true`\n   * prior to that change.\n   */\n  captureFullSnapshotOnFocus?: boolean;\n  /**\n   * Raw (uncompressed) UTF-8 byte cap for a single buffered events list before the store\n   * splits it into its own request. Larger values produce fewer, larger requests (the primary\n   * steady-state lever for request volume); smaller values split sooner. Payloads are gzipped\n   * on the wire, so several hundred KB of replay JSON compresses to well under 100 KB.\n   *\n   * Advanced/debug knob — the default already balances request volume against the server's\n   * decompressed-size split threshold. Clamped to a safe range; values outside it are clamped\n   * and logged. Defaults to the SDK's internal `DEFAULT_MAX_PERSISTED_EVENTS_SIZE_BYTES`.\n   *\n   * @defaultValue 6000000 — reflects the validated amp-on-amp perf config (SR-4646). Was\n   * `MAX_EVENT_LIST_SIZE` (2000000) prior to that change.\n   */\n  maxPersistedEventsSizeBytes?: number;\n  /**\n   * Raw (uncompressed) UTF-8 byte cap for a single rrweb event. Events larger than this are\n   * dropped (with a warning) both at capture time and as a pre-send backstop, because the SR\n   * ingest service rejects a single event above ~10 MB. Lower this to exercise drop behavior\n   * for large full snapshots while debugging.\n   *\n   * Advanced/debug knob. Clamped to a safe range; values outside it are clamped and logged.\n   * Defaults to the SDK's internal `MAX_SINGLE_EVENT_SIZE`.\n   *\n   * @defaultValue 9000000\n   */\n  maxSingleEventSizeBytes?: number;\n}\n\nexport interface FlushIntervalConfig {\n  /**\n   * Lower bound on the rrweb event-split interval in milliseconds. Also the increment\n   * added to the interval after each split. Must be > 0; values are clamped to a 100ms floor.\n   *\n   * @defaultValue 1000 — reflects the validated amp-on-amp perf config (SR-4646). Was `500`\n   * prior to that change.\n   */\n  minIntervalMs?: number;\n  /**\n   * Upper bound on the rrweb event-split interval in milliseconds. Must be >= `minIntervalMs`.\n   *\n   * @defaultValue 10000\n   */\n  maxIntervalMs?: number;\n}\n\nexport interface SessionReplayJoinedConfig extends SessionReplayLocalConfig {\n  captureEnabled?: boolean;\n  interactionConfig?: InteractionConfig;\n  loggingConfig?: LoggingConfig;\n  targetingConfig?: TargetingConfig;\n  minSessionDurationMs?: number;\n}\n\nexport interface SessionReplayConfigs {\n  localConfig: SessionReplayLocalConfig;\n  joinedConfig: SessionReplayJoinedConfig;\n  remoteConfig: SessionReplayRemoteConfig | undefined;\n}\nexport interface SessionReplayJoinedConfigGenerator {\n  generateJoinedConfig: () => Promise<SessionReplayConfigs>;\n}\n\nexport interface SessionReplayMetadata {\n  remoteConfig: SessionReplayRemoteConfig | undefined;\n  localConfig: SessionReplayLocalConfig;\n  joinedConfig: SessionReplayJoinedConfig;\n  framework?: {\n    name: string;\n    version: string;\n  };\n  sessionId: string | number | undefined;\n  hashValue?: number;\n  sampleRate: number;\n  replaySDKType: string | null;\n  replaySDKVersion: string | undefined;\n  standaloneSDKType: string;\n  standaloneSDKVersion: string | undefined;\n}\n\nexport interface SessionReplayVersion {\n  version: string;\n  type: SessionReplayType;\n}\n\n/**\n * Configuration options for session replay performance.\n */\nexport interface SessionReplayPerformanceConfig {\n  /**\n   * If enabled, event compression will be deferred to occur during the browser's idle periods.\n   */\n  enabled: boolean;\n  /**\n   * Optional timeout in milliseconds for the `requestIdleCallback` API.\n   * If specified, this value will be used to set a maximum time for the browser to wait\n   * before executing the deferred compression task, even if the browser is not idle.\n   */\n  timeout?: number;\n  /**\n   * If enabled, consecutive mutation events will be merged into a single event before\n   * compression, reducing stored event count without changing replay semantics.\n   * Defaults to true, reflecting the validated amp-on-amp perf config (SR-4646); set to\n   * false to disable merging.\n   */\n  mergeMutations?: boolean;\n  /**\n   * Performance configuration for interaction tracking (clicks, scrolls).\n   */\n  interaction?: InteractionPerformanceConfig;\n}\n\n/**\n * Performance configuration for interaction tracking, specifically for CSS selector generation.\n */\nexport interface InteractionPerformanceConfig {\n  /**\n   * Maximum time in milliseconds allowed for CSS selector generation.\n   * If selector generation takes longer than this, it will throw a timeout error.\n   * Default: undefined (no timeout limit)\n   */\n  timeoutMs?: number;\n  /**\n   * Maximum number of attempts to optimize/simplify the CSS selector path.\n   * Higher values may produce shorter selectors but take longer to compute.\n   * Default: 10000\n   */\n  maxNumberOfTries?: number;\n  /**\n   * Maximum number of CSS selector combinations to test for uniqueness.\n   * If more combinations would be generated, falls back to a simpler strategy.\n   * Default: 1000\n   */\n  threshold?: number;\n}\n\nexport type SessionReplayType = 'standalone' | 'plugin' | 'segment';\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/config/types.ts"],"names":[],"mappings":";;;AAwDa,QAAA,kBAAkB,GAAG,QAAQ,CAAC","sourcesContent":["import { IConfig, LogLevel, ILogger, IDiagnosticsClient } from '@amplitude/analytics-core';\nimport { StoreType, ConsoleLogLevel } from '../typings/session-replay';\nimport { TargetingFlag } from '@amplitude/targeting';\n\nexport interface SamplingConfig {\n  sample_rate: number;\n  capture_enabled: boolean;\n  min_session_duration_ms?: number;\n}\n\nexport interface InteractionConfig {\n  trackEveryNms?: number;\n  enabled: boolean; // defaults to false\n  batch: boolean; // defaults to false\n  /**\n   * UGC filter rules.\n   */\n  ugcFilterRules?: UGCFilterRule[];\n}\n\nexport interface LoggingConfig {\n  console: {\n    enabled: boolean;\n    levels: ConsoleLogLevel[];\n  };\n  network?: {\n    enabled: boolean;\n    body?: {\n      request?: boolean;\n      response?: boolean;\n      maxBodySizeBytes?: number;\n    };\n  };\n}\n\nexport type TargetingConfig = TargetingFlag;\n\nexport type SessionReplayRemoteConfig = {\n  sr_sampling_config?: SamplingConfig;\n  sr_privacy_config?: PrivacyConfig;\n  sr_interaction_config?: InteractionConfig;\n  sr_logging_config?: LoggingConfig;\n  sr_targeting_config?: TargetingConfig;\n};\n\nexport interface SessionReplayRemoteConfigAPIResponse {\n  configs: {\n    sessionReplay: SessionReplayRemoteConfig;\n  };\n}\n\nexport type MaskLevel =\n  | 'light' // only mask a subset of inputs that's deemed sensitive - password, credit card, telephone #, email. These are information we never want to capture.\n  | 'medium' // mask all form fields (inputs); page text is captured as-is\n  | 'conservative'; // mask all inputs and all texts\n\nexport const DEFAULT_MASK_LEVEL = 'medium';\n\n// err on the side of excluding more\nexport type PrivacyConfig = {\n  blockSelector?: string | string[]; // exclude in the UI\n  defaultMaskLevel?: MaskLevel;\n  maskSelector?: string[];\n  unmaskSelector?: string[];\n  maskAttributes?: string[]; // HTML attribute names to mask (e.g. [\"placeholder\", \"aria-label\"])\n  /**\n   * Per-URL overrides for `defaultMaskLevel`. Each entry contains a glob pattern (`match`)\n   * and a `maskLevel` to apply when the current page URL matches that pattern.\n   * Rules are evaluated in order; the first match wins. Remote rules take precedence\n   * over local rules (remote entries are prepended before local entries).\n   *\n   * @example\n   * urlMaskLevels: [\n   *   { match: 'https://example.com/checkout/*', maskLevel: 'conservative' },\n   *   { match: 'https://example.com/public/*',   maskLevel: 'light' },\n   * ]\n   */\n  urlMaskLevels?: Array<{ match: string; maskLevel: MaskLevel }>;\n};\n\n/**\n * UGC filter rule.\n */\nexport type UGCFilterRule = {\n  /**\n   * The selector of the UGC element.\n   */\n  selector: string;\n  /**\n   * The replacement text for the UGC element.\n   */\n  replacement: string;\n};\n\nexport interface CrossOriginIframesConfig {\n  enabled: boolean;\n  /**\n   * When true (default), the parent SDK sends start/stop signals to child iframes via\n   * postMessage, keeping their recording lifecycle in sync with the parent.\n   *\n   * **Privacy note:** The child page's rrweb instance performs its own DOM serialization,\n   * so the parent's privacy config (mask levels, block selectors) does NOT automatically\n   * apply inside the iframe. Privacy settings must be configured independently on the child page.\n   *\n   * **Third-party iframes:** Cannot capture iframes you don't control (e.g. Stripe, Google\n   * Maps) — both parent and child pages must load the SDK with `crossOriginIframes.enabled: true`.\n   *\n   * Set to `false` to skip coordination and manage the child recording lifecycle yourself.\n   * @defaultValue true\n   */\n  coordinateChildren?: boolean;\n}\n\nexport interface SessionReplayLocalConfig extends IConfig {\n  apiKey: string;\n  loggerProvider: ILogger;\n  /**\n   * Optional diagnostics client used to ship SR decision/targeting telemetry to Amplitude's\n   * diagnostics backend (independent of whether a replay is recorded). In plugin mode this is\n   * forwarded from the analytics SDK's already-initialized client. No-op when absent or when\n   * diagnostics is not sampled in. See DiagnosticsClient in @amplitude/analytics-core.\n   */\n  diagnosticsClient?: IDiagnosticsClient;\n  /**\n   * Standalone SR only: when no `diagnosticsClient` is provided (i.e. SR is not running as the\n   * analytics plugin), opt in to having SR create its own client so TRC/recording diagnostics are\n   * still shipped. Ignored when a `diagnosticsClient` is supplied. @defaultValue false\n   */\n  diagnosticsEnabled?: boolean;\n  /**\n   * Standalone SR only: sample rate (0..1) for the diagnostics client SR creates when none is\n   * provided. A positive value also implies opting in. @defaultValue 0\n   */\n  diagnosticsSampleRate?: number;\n  /**\n   * LogLevel.None or LogLevel.Error or LogLevel.Warn or LogLevel.Verbose or LogLevel.Debug.\n   * Sets the log level.\n   *\n   * @defaultValue LogLevel.Warn\n   */\n  logLevel: LogLevel;\n  /**\n   * The maximum number of retries allowed for sending replay events.\n   * Once this limit is reached, failed events will no longer be sent.\n   *\n   * @defaultValue 2\n   */\n  flushMaxRetries: number;\n  /**\n   * Use this option to control how many sessions to select for replay collection.\n   * The number should be a decimal between 0 and 1, for example 0.4, representing\n   * the fraction of sessions to have randomly selected for replay collection.\n   * Over a large number of sessions, 0.4 would select 40% of those sessions.\n   * Sample rates as small as six decimal places (0.000001) are supported.\n   *\n   * @defaultValue 0\n   */\n  sampleRate: number;\n  privacyConfig?: PrivacyConfig;\n  /**\n   * Adds additional debug event property to help debug instrumentation issues\n   * (such as mismatching apps). Only recommended for debugging initial setup,\n   * and not recommended for production.\n   */\n  debugMode?: boolean;\n  /**\n   * Specifies the endpoint URL to fetch remote configuration.\n   * If provided, it overrides the default server zone configuration.\n   */\n  configServerUrl?: string;\n  /**\n   * Specifies the endpoint URL for sending session replay data.\n   * If provided, it overrides the default server zone configuration.\n   */\n  trackServerUrl?: string;\n  /**\n   * If stylesheets are inlined, the contents of the stylesheet will be stored.\n   * During replay, the stored stylesheet will be used instead of attempting to fetch it remotely.\n   * This prevents replays from appearing broken due to missing stylesheets.\n   * Note: Inlining stylesheets may not work in all cases.\n   */\n  shouldInlineStylesheet?: boolean;\n  version?: SessionReplayVersion;\n  /**\n   * Performance configuration config. If enabled, we will defer compression\n   * to be done during the browser's idle periods.\n   */\n  performanceConfig?: SessionReplayPerformanceConfig;\n  /**\n   * Specifies how replay events should be stored. `idb` uses IndexedDB to persist replay events\n   * when all events cannot be sent during capture. `memory` stores replay events only in memory,\n   * meaning events are lost when the page is closed. If IndexedDB is unavailable, the system falls back to `memory`.\n   *\n   * @defaultValue 'memory' — reflects the validated amp-on-amp perf config (SR-4646). `memory`\n   * drops cross-navigation persistence (unsent events do not survive a full page reload), which\n   * is the intended trade-off for lower IDB overhead.\n   */\n  storeType: StoreType;\n\n  /**\n   * If true, the SDK will compress replay events using a web worker.\n   * This offloads compression to a separate thread, improving performance on the main thread.\n   * Set to `false` to keep compression on the main thread.\n   *\n   * @defaultValue true — reflects the validated amp-on-amp perf config (SR-4646). Was `false`\n   * prior to that change.\n   */\n  useWebWorker?: boolean;\n\n  /**\n   * Controls transport-layer gzip compression of session replay request bodies.\n   * When true (default), the SDK gzip-compresses the JSON request body via the browser's\n   * `CompressionStream` API and sets `Content-Encoding: gzip` on the POST. When false,\n   * the SDK sends the raw JSON body with no `Content-Encoding` header.\n   *\n   * Disabling is intended as a debugging / safety opt-out (e.g. for diagnosing\n   * server-side decompression issues); it increases egress bytes and is not\n   * recommended for production.\n   *\n   * Note: This is independent of `useWebWorker` / `performanceConfig`, which control\n   * per-event rrweb compression that runs before events are queued.\n   *\n   * @defaultValue true\n   */\n  enableTransportCompression?: boolean;\n\n  /**\n   * Milliseconds to wait for a send request before aborting it. `fetch()` has no native\n   * timeout, so a request stuck \"pending\" would block the serial flush loop indefinitely;\n   * the SDK aborts after this many ms and routes the abort as a retryable failure.\n   *\n   * Set to `0` (or a negative value) to disable the timeout entirely — note this\n   * reintroduces the head-of-line-blocking risk a wedged request can cause, so it is\n   * intended only as a diagnostic/experiment opt-out.\n   *\n   * Tuning this higher is useful when large, slow-but-succeeding uploads are being aborted\n   * at the default and counted as failures (which also triggers a retry, inflating request\n   * volume / throttle pressure).\n   *\n   * @defaultValue 10000\n   */\n  sendTimeoutMs?: number;\n\n  userProperties?: { [key: string]: any };\n\n  /**\n   * If true, applies a background color to blocked elements in the replay.\n   * This helps visualize which elements are blocked from being captured.\n   */\n  applyBackgroundColorToBlockedElements?: boolean;\n  /**\n   * Enables URL change polling as a fallback for SPA route tracking.\n   * When enabled, the SDK will periodically check for URL changes every second\n   * in addition to patching the History API. This is useful for edge cases where\n   * route changes might bypass the standard History API methods.\n   *\n   * @defaultValue false\n   */\n  enableUrlChangePolling?: boolean;\n  /**\n   * Specifies the interval in milliseconds for URL change polling when enableUrlChangePolling is true.\n   * The SDK will check for URL changes at this interval as a fallback for SPA route tracking.\n   *\n   * @defaultValue 1000\n   */\n  urlChangePollingInterval?: number;\n  /**\n   * Whether to capture document title in URL change events.\n   * When disabled, the title field will be empty in URL change events.\n   *\n   * @defaultValue false\n   */\n  captureDocumentTitle?: boolean;\n  interactionConfig?: InteractionConfig;\n  /**\n   * When true (default), the CSS rules of any `adoptedStyleSheets` on shadow roots and\n   * the document are serialized **inline** within the full snapshot. This makes the snapshot\n   * self-contained so that shadow DOM styles are replayed correctly even if subsequent\n   * incremental `AdoptedStyleSheet` events are dropped in transit.\n   *\n   * Set to `false` to revert to the legacy behavior where adopted stylesheet rules are\n   * emitted as separate incremental events (which may be lost if delivery is unreliable).\n   * Only consider opting out if snapshot payload size is a critical concern.\n   *\n   * @defaultValue true\n   */\n  captureAdoptedStyleSheets?: boolean;\n  /**\n   * Enables recording of cross-origin iframes. Both the parent page and each child iframe\n   * page must load the Amplitude Session Replay SDK with this option enabled.\n   *\n   * When enabled, rrweb uses `postMessage` to relay child DOM events to the parent, which\n   * merges them into a single unified event stream.\n   */\n  crossOriginIframes?: CrossOriginIframesConfig;\n  /** Interval in ms at which the SDK takes a full DOM snapshot. Disabled by default — periodic snapshots are expensive. Recommended value: 300000 (5 min). */\n  fullSnapshotIntervalMs?: number;\n  /**\n   * Controls how often the SDK splits buffered rrweb events into a sequence and dispatches\n   * the resulting batch to the server. The interval starts at `minIntervalMs` and grows by\n   * `minIntervalMs` after each split, capped at `maxIntervalMs`. Lowering values increases\n   * replay availability latency improvements at the cost of more requests; raising them\n   * reduces request volume (and 200+`X-Session-Replay-Event-Skipped` throttling responses)\n   * at the cost of slightly delayed replay availability.\n   *\n   * Defaults to `{ minIntervalMs: 1000, maxIntervalMs: 10_000 }`, reflecting the validated\n   * amp-on-amp perf config (SR-4646); the `minIntervalMs` default was `500` prior to that\n   * change. Tune up if the server is back-pressuring the SDK on session start.\n   */\n  flushIntervalConfig?: FlushIntervalConfig;\n  /**\n   * When true, every rrweb full snapshot is flushed to the server immediately so replays\n   * become playable as early as possible. When false (default), full-snapshot sends are\n   * deferred to the normal interval/size flush cadence instead. The snapshot is still\n   * compressed and buffered immediately either way (ordering and page-exit beacon coverage\n   * are preserved); only the eager network send is suppressed. The default-off behavior\n   * reduces request volume for pages that produce many full snapshots (e.g. focus-driven or\n   * `fullSnapshotIntervalMs` checkouts), especially when many SDK instances run on the same\n   * page.\n   *\n   * @defaultValue false — reflects the validated amp-on-amp perf config (SR-4646). Was `true`\n   * prior to that change.\n   */\n  eagerFullSnapshotSend?: boolean;\n  /**\n   * When true, the window `focus` listener forces a fresh rrweb full snapshot\n   * (`takeFullSnapshot`) every time the page regains focus, so the replay reflects any DOM\n   * changes that happened while the tab was backgrounded. When false (default), the on-focus\n   * full snapshot is skipped entirely (recording simply continues from the existing stream).\n   *\n   * On pages with heavy focus churn (e.g. embedded iframes, inline editors that repeatedly\n   * steal and return focus) this fires constantly, and when combined with\n   * `eagerFullSnapshotSend` each focus produces an immediate network send — the primary\n   * driver of focus-driven request storms. The default-off behavior removes the snapshot (and\n   * therefore the send) at the cost of slightly staler post-focus frames.\n   *\n   * @defaultValue false — reflects the validated amp-on-amp perf config (SR-4646). Was `true`\n   * prior to that change.\n   */\n  captureFullSnapshotOnFocus?: boolean;\n  /**\n   * Raw (uncompressed) UTF-8 byte cap for a single buffered events list before the store\n   * splits it into its own request. Larger values produce fewer, larger requests (the primary\n   * steady-state lever for request volume); smaller values split sooner. Payloads are gzipped\n   * on the wire, so several hundred KB of replay JSON compresses to well under 100 KB.\n   *\n   * Advanced/debug knob — the default already balances request volume against the server's\n   * decompressed-size split threshold. Clamped to a safe range; values outside it are clamped\n   * and logged. Defaults to the SDK's internal `DEFAULT_MAX_PERSISTED_EVENTS_SIZE_BYTES`.\n   *\n   * @defaultValue 6000000 — reflects the validated amp-on-amp perf config (SR-4646). Was\n   * `MAX_EVENT_LIST_SIZE` (2000000) prior to that change.\n   */\n  maxPersistedEventsSizeBytes?: number;\n  /**\n   * Raw (uncompressed) UTF-8 byte cap for a single rrweb event. Events larger than this are\n   * dropped (with a warning) both at capture time and as a pre-send backstop, because the SR\n   * ingest service rejects a single event above ~10 MB. Lower this to exercise drop behavior\n   * for large full snapshots while debugging.\n   *\n   * Advanced/debug knob. Clamped to a safe range; values outside it are clamped and logged.\n   * Defaults to the SDK's internal `MAX_SINGLE_EVENT_SIZE`.\n   *\n   * @defaultValue 9000000\n   */\n  maxSingleEventSizeBytes?: number;\n}\n\nexport interface FlushIntervalConfig {\n  /**\n   * Lower bound on the rrweb event-split interval in milliseconds. Also the increment\n   * added to the interval after each split. Must be > 0; values are clamped to a 100ms floor.\n   *\n   * @defaultValue 1000 — reflects the validated amp-on-amp perf config (SR-4646). Was `500`\n   * prior to that change.\n   */\n  minIntervalMs?: number;\n  /**\n   * Upper bound on the rrweb event-split interval in milliseconds. Must be >= `minIntervalMs`.\n   *\n   * @defaultValue 10000\n   */\n  maxIntervalMs?: number;\n}\n\nexport interface SessionReplayJoinedConfig extends SessionReplayLocalConfig {\n  captureEnabled?: boolean;\n  interactionConfig?: InteractionConfig;\n  loggingConfig?: LoggingConfig;\n  targetingConfig?: TargetingConfig;\n  minSessionDurationMs?: number;\n}\n\nexport interface SessionReplayConfigs {\n  localConfig: SessionReplayLocalConfig;\n  joinedConfig: SessionReplayJoinedConfig;\n  remoteConfig: SessionReplayRemoteConfig | undefined;\n}\nexport interface SessionReplayJoinedConfigGenerator {\n  generateJoinedConfig: () => Promise<SessionReplayConfigs>;\n}\n\nexport interface SessionReplayMetadata {\n  remoteConfig: SessionReplayRemoteConfig | undefined;\n  localConfig: SessionReplayLocalConfig;\n  joinedConfig: SessionReplayJoinedConfig;\n  framework?: {\n    name: string;\n    version: string;\n  };\n  sessionId: string | number | undefined;\n  hashValue?: number;\n  sampleRate: number;\n  replaySDKType: string | null;\n  replaySDKVersion: string | undefined;\n  standaloneSDKType: string;\n  standaloneSDKVersion: string | undefined;\n}\n\nexport interface SessionReplayVersion {\n  version: string;\n  type: SessionReplayType;\n}\n\n/**\n * Configuration options for session replay performance.\n */\nexport interface SessionReplayPerformanceConfig {\n  /**\n   * If enabled, event compression will be deferred to occur during the browser's idle periods.\n   */\n  enabled: boolean;\n  /**\n   * Optional timeout in milliseconds for the `requestIdleCallback` API.\n   * If specified, this value will be used to set a maximum time for the browser to wait\n   * before executing the deferred compression task, even if the browser is not idle.\n   */\n  timeout?: number;\n  /**\n   * If enabled, consecutive mutation events will be merged into a single event before\n   * compression, reducing stored event count without changing replay semantics.\n   * Defaults to true, reflecting the validated amp-on-amp perf config (SR-4646); set to\n   * false to disable merging.\n   */\n  mergeMutations?: boolean;\n  /**\n   * Performance configuration for interaction tracking (clicks, scrolls).\n   */\n  interaction?: InteractionPerformanceConfig;\n}\n\n/**\n * Performance configuration for interaction tracking, specifically for CSS selector generation.\n */\nexport interface InteractionPerformanceConfig {\n  /**\n   * Maximum time in milliseconds allowed for CSS selector generation.\n   * If selector generation takes longer than this, it will throw a timeout error.\n   * Default: undefined (no timeout limit)\n   */\n  timeoutMs?: number;\n  /**\n   * Maximum number of attempts to optimize/simplify the CSS selector path.\n   * Higher values may produce shorter selectors but take longer to compute.\n   * Default: 10000\n   */\n  maxNumberOfTries?: number;\n  /**\n   * Maximum number of CSS selector combinations to test for uniqueness.\n   * If more combinations would be generated, falls back to a simpler strategy.\n   * Default: 1000\n   */\n  threshold?: number;\n}\n\nexport type SessionReplayType = 'standalone' | 'plugin' | 'segment';\n"]}

package/lib/cjs/diagnostics.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Centralized names for Session Replay diagnostics shipped via the analytics DiagnosticsClient.
+ *
+ * Every name shares SR_DIAGNOSTIC_PREFIX so they group together in DataDog as
+ * `sdk.diagnostics.sr.trc.*`. The diagnostics pipeline prepends `sdk.diagnostics.` and appends
+ * `.count` to counters / `.{min,max,avg,count}` to histograms; events are forwarded to DataDog
+ * Logs keyed by `event_name`. Keep ALL SR diagnostic names here so the prefix stays unified —
+ * changing the namespace is then a one-line edit.
+ */
+export declare const SR_DIAGNOSTIC_PREFIX = "sr.trc";
+export declare const SrDiagnostic: {
+    readonly init: "sr.trc.init";
+    readonly configSource: (source: string) => string;
+    readonly configHasTargeting: "sr.trc.config.has_targeting";
+    readonly configNoTargeting: "sr.trc.config.no_targeting";
+    readonly configFetchFailed: "sr.trc.config.fetch_failed";
+    readonly configReceived: "sr.trc.config.received";
+    readonly evalTrigger: (trigger: string) => string;
+    readonly evalNoConfig: "sr.trc.eval.no_config";
+    readonly evalMissingPrereq: "sr.trc.eval.missing_prereq";
+    readonly evalMatch: "sr.trc.eval.match";
+    readonly evalNoMatch: "sr.trc.eval.no_match";
+    readonly evalError: "sr.trc.eval.error";
+    readonly evalStaleDiscarded: "sr.trc.eval.stale_discarded";
+    readonly evalSkippedAlreadyMatched: "sr.trc.eval.skipped_already_matched";
+    readonly evalDurationMs: "sr.trc.eval.duration_ms";
+    readonly evalEvent: "sr.trc.eval";
+    readonly evalResult: "sr.trc.eval.result";
+    readonly recordStarted: "sr.trc.record.started";
+    readonly recordNoRecordFn: "sr.trc.record.no_record_fn";
+    readonly sendSuppressedMinDuration: "sr.trc.send.suppressed_min_duration";
+    readonly gateNoIdentifiers: "sr.trc.gate.no_identifiers";
+    readonly gateCaptureDisabled: "sr.trc.gate.capture_disabled";
+    readonly gateOptOut: "sr.trc.gate.optout";
+    readonly gateTrcMatch: "sr.trc.gate.trc_match";
+    readonly gateTrcNoMatch: "sr.trc.gate.trc_no_match";
+    readonly gateSampleIn: "sr.trc.gate.sample_in";
+    readonly gateSampleOut: "sr.trc.gate.sample_out";
+    readonly decision: "sr.trc.decision";
+    readonly urlChange: "sr.trc.url_change";
+    readonly urlChangeEvent: "sr.trc.url_change";
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/cjs/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAI7C,eAAO,MAAM,YAAY;;oCAKA,MAAM;;;;;oCAQN,MAAM;;;;;;;;;;;;;;;;;;;;;;;;CA8BrB,CAAC"}

package/lib/cjs/diagnostics.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SrDiagnostic = exports.SR_DIAGNOSTIC_PREFIX = void 0;
+/**
+ * Centralized names for Session Replay diagnostics shipped via the analytics DiagnosticsClient.
+ *
+ * Every name shares SR_DIAGNOSTIC_PREFIX so they group together in DataDog as
+ * `sdk.diagnostics.sr.trc.*`. The diagnostics pipeline prepends `sdk.diagnostics.` and appends
+ * `.count` to counters / `.{min,max,avg,count}` to histograms; events are forwarded to DataDog
+ * Logs keyed by `event_name`. Keep ALL SR diagnostic names here so the prefix stays unified —
+ * changing the namespace is then a one-line edit.
+ */
+exports.SR_DIAGNOSTIC_PREFIX = 'sr.trc';
+var p = exports.SR_DIAGNOSTIC_PREFIX;
+exports.SrDiagnostic = {
+    // ── Init (Q1: did init even happen?) ─────────────────────────────────────
+    init: "".concat(p, ".init"),
+    // ── Remote config fetch (joined-config) ──────────────────────────────────
+    configSource: function (source) { return "".concat(p, ".config.source.").concat(source); },
+    configHasTargeting: "".concat(p, ".config.has_targeting"),
+    configNoTargeting: "".concat(p, ".config.no_targeting"),
+    configFetchFailed: "".concat(p, ".config.fetch_failed"),
+    configReceived: "".concat(p, ".config.received"),
+    // ── Targeting evaluation (evaluateTargetingAndCapture) ────────────────────
+    // Q2 (did eval run?), Q3 (working/failed?), Q4 (missing value?), Q5 (all params).
+    evalTrigger: function (trigger) { return "".concat(p, ".eval.").concat(trigger); },
+    evalNoConfig: "".concat(p, ".eval.no_config"),
+    evalMissingPrereq: "".concat(p, ".eval.missing_prereq"),
+    evalMatch: "".concat(p, ".eval.match"),
+    evalNoMatch: "".concat(p, ".eval.no_match"),
+    evalError: "".concat(p, ".eval.error"),
+    evalStaleDiscarded: "".concat(p, ".eval.stale_discarded"),
+    evalSkippedAlreadyMatched: "".concat(p, ".eval.skipped_already_matched"),
+    evalDurationMs: "".concat(p, ".eval.duration_ms"),
+    evalEvent: "".concat(p, ".eval"),
+    evalResult: "".concat(p, ".eval.result"),
+    // ── Recording execution (getShouldRecord said yes — did rrweb actually start?) ──
+    recordStarted: "".concat(p, ".record.started"),
+    recordNoRecordFn: "".concat(p, ".record.no_record_fn"),
+    sendSuppressedMinDuration: "".concat(p, ".send.suppressed_min_duration"),
+    // ── Record / no-record gate (getShouldRecord) ────────────────────────────
+    gateNoIdentifiers: "".concat(p, ".gate.no_identifiers"),
+    gateCaptureDisabled: "".concat(p, ".gate.capture_disabled"),
+    gateOptOut: "".concat(p, ".gate.optout"),
+    gateTrcMatch: "".concat(p, ".gate.trc_match"),
+    gateTrcNoMatch: "".concat(p, ".gate.trc_no_match"),
+    gateSampleIn: "".concat(p, ".gate.sample_in"),
+    gateSampleOut: "".concat(p, ".gate.sample_out"),
+    decision: "".concat(p, ".decision"),
+    // ── SPA URL change (setupUrlChangeListener) ──────────────────────────────
+    urlChange: "".concat(p, ".url_change"),
+    urlChangeEvent: "".concat(p, ".url_change"), // event (with props); same name, logs vs metric
+};
+//# sourceMappingURL=diagnostics.js.map

package/lib/cjs/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACU,QAAA,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,IAAM,CAAC,GAAG,4BAAoB,CAAC;AAElB,QAAA,YAAY,GAAG;IAC1B,4EAA4E;IAC5E,IAAI,EAAE,UAAG,CAAC,UAAO;IAEjB,4EAA4E;IAC5E,YAAY,EAAE,UAAC,MAAc,IAAK,OAAA,UAAG,CAAC,4BAAkB,MAAM,CAAE,EAA9B,CAA8B;IAChE,kBAAkB,EAAE,UAAG,CAAC,0BAAuB;IAC/C,iBAAiB,EAAE,UAAG,CAAC,yBAAsB;IAC7C,iBAAiB,EAAE,UAAG,CAAC,yBAAsB;IAC7C,cAAc,EAAE,UAAG,CAAC,qBAAkB;IAEtC,6EAA6E;IAC7E,kFAAkF;IAClF,WAAW,EAAE,UAAC,OAAe,IAAK,OAAA,UAAG,CAAC,mBAAS,OAAO,CAAE,EAAtB,CAAsB;IACxD,YAAY,EAAE,UAAG,CAAC,oBAAiB;IACnC,iBAAiB,EAAE,UAAG,CAAC,yBAAsB;IAC7C,SAAS,EAAE,UAAG,CAAC,gBAAa;IAC5B,WAAW,EAAE,UAAG,CAAC,mBAAgB;IACjC,SAAS,EAAE,UAAG,CAAC,gBAAa;IAC5B,kBAAkB,EAAE,UAAG,CAAC,0BAAuB;IAC/C,yBAAyB,EAAE,UAAG,CAAC,kCAA+B;IAC9D,cAAc,EAAE,UAAG,CAAC,sBAAmB;IACvC,SAAS,EAAE,UAAG,CAAC,UAAO;IACtB,UAAU,EAAE,UAAG,CAAC,iBAAc;IAE9B,mFAAmF;IACnF,aAAa,EAAE,UAAG,CAAC,oBAAiB;IACpC,gBAAgB,EAAE,UAAG,CAAC,yBAAsB;IAC5C,yBAAyB,EAAE,UAAG,CAAC,kCAA+B;IAE9D,4EAA4E;IAC5E,iBAAiB,EAAE,UAAG,CAAC,yBAAsB;IAC7C,mBAAmB,EAAE,UAAG,CAAC,2BAAwB;IACjD,UAAU,EAAE,UAAG,CAAC,iBAAc;IAC9B,YAAY,EAAE,UAAG,CAAC,oBAAiB;IACnC,cAAc,EAAE,UAAG,CAAC,uBAAoB;IACxC,YAAY,EAAE,UAAG,CAAC,oBAAiB;IACnC,aAAa,EAAE,UAAG,CAAC,qBAAkB;IACrC,QAAQ,EAAE,UAAG,CAAC,cAAW;IAEzB,4EAA4E;IAC5E,SAAS,EAAE,UAAG,CAAC,gBAAa;IAC5B,cAAc,EAAE,UAAG,CAAC,gBAAa,EAAE,gDAAgD;CAC3E,CAAC","sourcesContent":["/**\n * Centralized names for Session Replay diagnostics shipped via the analytics DiagnosticsClient.\n *\n * Every name shares SR_DIAGNOSTIC_PREFIX so they group together in DataDog as\n * `sdk.diagnostics.sr.trc.*`. The diagnostics pipeline prepends `sdk.diagnostics.` and appends\n * `.count` to counters / `.{min,max,avg,count}` to histograms; events are forwarded to DataDog\n * Logs keyed by `event_name`. Keep ALL SR diagnostic names here so the prefix stays unified —\n * changing the namespace is then a one-line edit.\n */\nexport const SR_DIAGNOSTIC_PREFIX = 'sr.trc';\n\nconst p = SR_DIAGNOSTIC_PREFIX;\n\nexport const SrDiagnostic = {\n  // ── Init (Q1: did init even happen?) ─────────────────────────────────────\n  init: `${p}.init`, // counter + event(with props): fires once per init()\n\n  // ── Remote config fetch (joined-config) ──────────────────────────────────\n  configSource: (source: string) => `${p}.config.source.${source}`,\n  configHasTargeting: `${p}.config.has_targeting`,\n  configNoTargeting: `${p}.config.no_targeting`,\n  configFetchFailed: `${p}.config.fetch_failed`,\n  configReceived: `${p}.config.received`, // event (with props)\n\n  // ── Targeting evaluation (evaluateTargetingAndCapture) ────────────────────\n  // Q2 (did eval run?), Q3 (working/failed?), Q4 (missing value?), Q5 (all params).\n  evalTrigger: (trigger: string) => `${p}.eval.${trigger}`, // init | urlchange | event\n  evalNoConfig: `${p}.eval.no_config`,\n  evalMissingPrereq: `${p}.eval.missing_prereq`, // Q4: sessionId/config/deviceId missing\n  evalMatch: `${p}.eval.match`,\n  evalNoMatch: `${p}.eval.no_match`,\n  evalError: `${p}.eval.error`, // Q3: targeting engine threw\n  evalStaleDiscarded: `${p}.eval.stale_discarded`,\n  evalSkippedAlreadyMatched: `${p}.eval.skipped_already_matched`,\n  evalDurationMs: `${p}.eval.duration_ms`, // histogram\n  evalEvent: `${p}.eval`, // event (with ALL eval params — Q5)\n  evalResult: `${p}.eval.result`, // event: raw engine verdict (variantKey) — why match/no-match\n\n  // ── Recording execution (getShouldRecord said yes — did rrweb actually start?) ──\n  recordStarted: `${p}.record.started`, // event: capture began (carries the srId the replay uploads under)\n  recordNoRecordFn: `${p}.record.no_record_fn`, // counter + event: rrweb import returned nothing\n  sendSuppressedMinDuration: `${p}.send.suppressed_min_duration`, // counter: events held back by min_session_duration\n\n  // ── Record / no-record gate (getShouldRecord) ────────────────────────────\n  gateNoIdentifiers: `${p}.gate.no_identifiers`, // Q4: no config/sessionId at gate time\n  gateCaptureDisabled: `${p}.gate.capture_disabled`,\n  gateOptOut: `${p}.gate.optout`,\n  gateTrcMatch: `${p}.gate.trc_match`,\n  gateTrcNoMatch: `${p}.gate.trc_no_match`,\n  gateSampleIn: `${p}.gate.sample_in`,\n  gateSampleOut: `${p}.gate.sample_out`,\n  decision: `${p}.decision`, // event (with props)\n\n  // ── SPA URL change (setupUrlChangeListener) ──────────────────────────────\n  urlChange: `${p}.url_change`,\n  urlChangeEvent: `${p}.url_change`, // event (with props); same name, logs vs metric\n} as const;\n"]}

package/lib/cjs/session-replay.d.ts

@@ -19,6 +19,7 @@ export declare class SessionReplay implements AmplitudeSessionReplay {
     sessionTargetingMatch: boolean;
     private lastTargetingParams?;
     private lastShouldRecordDecision?;
+    private trcDiagnosticSessionId;
     pageLeaveFns: PageLeaveFn[];
     sessionStartTime: number | undefined;
     rrwebEventManager: EventsManagerWithBeacon<'replay'> | undefined;
@@ -88,6 +89,30 @@ export declare class SessionReplay implements AmplitudeSessionReplay {
     sendEvents(sessionId?: string | number): void;
     initialize(shouldSendStoredEvents?: boolean): Promise<void>;
     shouldOptOut(): boolean | undefined;
+    /**
+     * Increment a diagnostics counter so the team can see the distribution of recording decisions
+     * across a customer's sessions (e.g. lots of sr.gate.trc_no_match => rule isn't matching).
+     * Ships via the analytics SDK's DiagnosticsClient. No-op when there's no client or diagnostics
+     * isn't sampled in; never throws — diagnostics must never interfere with recording.
+     */
+    private incrementDiagnostic;
+    /**
+     * Record a diagnostics histogram value (min/max/avg/count in DataDog). Same best-effort, never-
+     * throws contract as incrementDiagnostic. Use for latencies/sizes, not per-call counts.
+     */
+    private recordDiagnosticHistogram;
+    /**
+     * Record a diagnostics EVENT with properties. Events are forwarded to DataDog Logs, so the
+     * properties become queryable fields (e.g. @matched, @pageUrl). Use sparingly vs counters: the
+     * client caps in-memory events (~10 per save interval), so this is for context-rich signals at
+     * meaningful decision points, not per-call tallies. Best-effort, never throws.
+     */
+    private recordDiagnosticEvent;
+    /**
+     * Emit a single rich TRC decision snapshot per session to diagnostics — surfaced even when
+     * nothing records (the exact case customers can't reproduce locally).
+     */
+    private recordTrcDecisionDiagnostic;
     getShouldRecord(): boolean;
     getBlockSelectors(): string | string[] | undefined;
     getMaskTextSelectors(): string | undefined;

package/lib/cjs/session-replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-replay.d.ts","sourceRoot":"","sources":["../../src/session-replay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-replay.d.ts","sourceRoot":"","sources":["../../src/session-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,OAAO,EASR,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EACL,aAAa,EACb,yBAAyB,EACzB,kCAAkC,EAInC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,gBAAgB,EASjB,MAAM,aAAa,CAAC;AAWrB,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAuB,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAcvF,OAAO,EACL,sBAAsB,EACtB,0BAA0B,IAAI,mCAAmC,EAIjE,kBAAkB,IAAI,mBAAmB,EACzC,oBAAoB,EACpB,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAOlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD,KAAK,WAAW,GAAG,CAAC,CAAC,EAAE,mBAAmB,GAAG,KAAK,KAAK,IAAI,CAAC;AAE5D,qBAAa,aAAc,YAAW,sBAAsB;IAC1D,IAAI,SAAuC;IAC3C,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;IAC9C,qBAAqB,EAAE,kCAAkC,GAAG,SAAS,CAAC;IACtE,WAAW,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC7C,aAAa,CAAC,EAAE,mCAAmC,CAAC,QAAQ,GAAG,aAAa,EAAE,MAAM,CAAC,CAAC;IACtF,cAAc,EAAE,OAAO,CAAC;IACxB,oBAAoB,EAAE,UAAU,CAAC,cAAc,CAAC,GAAG,IAAI,CAAQ;IAC/D,UAAU,SAAK;IACf,eAAe,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,qBAAqB,UAAS;IAC9B,OAAO,CAAC,mBAAmB,CAAC,CAA8B;IAC1D,OAAO,CAAC,wBAAwB,CAAC,CAAU;IAI3C,OAAO,CAAC,sBAAsB,CAA0C;IAOxE,YAAY,EAAE,WAAW,EAAE,CAAM;IACjC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,iBAAiB,EAAE,uBAAuB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IACjE;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAK;IAChC,+EAA+E;IAC/E,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,UAAU,CAAC,CAAiB;IACpC,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,gBAAgB,CAAC,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAoC;IAGpD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,iBAAiB,CAAmE;IAE5F,gFAAgF;IAChF,OAAO,CAAC,cAAc,CAAM;IAE5B,OAAO,CAAC,oCAAoC,CAAwB;IAEpE,yFAAyF;IACzF,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,4BAA4B,CAA6C;IACjF,OAAO,CAAC,8BAA8B,CAA6B;IACnE,qEAAqE;IACrE,OAAO,CAAC,oCAAoC,CAAK;;IAMjD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB;IAIlD,OAAO,CAAC,sBAAsB,CAmB5B;IAEF;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAiD9B;;;;;;;;;OASG;IACH,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,0BAA0B;cAKlB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB;IA2MnE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAIpD,iBAAiB,CACrB,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,CAAA;KAAE;IA6EvD,0BAA0B;;;IAsC1B,YAAY,aAEV;IAEF,aAAa,aAgBX;IAEF;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAQvB;IAEF,2BAA2B,oBACR,2BAA2B,mGA+I5C;IAEF,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAuDhC,UAAU,CAAC,sBAAsB,UAAQ;IAgB/C,YAAY;IAUZ;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAYjC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAsB7B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IA6BnC,eAAe;IA0Ef,iBAAiB,IAAI,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAWlD,oBAAoB,IAAI,MAAM,GAAG,SAAS;IAgCpC,mBAAmB,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS;YAyCpD,iBAAiB;IAezB,YAAY,CAAC,iBAAiB,UAAO;YAmB7B,aAAa;IAmI3B,OAAO,CAAC,uBAAuB;IAuD/B,OAAO,CAAC,wBAAwB;IAkChC,mBAAmB,cACN,gBAAgB;;kDAmC3B;IAEF,mBAAmB,aAgBjB;IAEF,WAAW;IAIX,YAAY;IAIN,KAAK,CAAC,QAAQ,UAAQ;IAS5B,QAAQ;IASR,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,WAAW;YAyBL,0BAA0B;CAUzC"}