@corbado/observe 1.10.1 → 1.11.0

package/dist/analysis/tracker-core.mjs

@@ -0,0 +1,1352 @@
+// src/tracker-core.ts
+import { reserveCaptureSeq } from "./low-events/capture-sequence.mjs";
+import { readSourcePath } from "./readers/page.mjs";
+import { readUserAgent } from "./readers/device.mjs";
+import { SharedWindowObserver, getCapturePageId } from "./low-events/shared-window-observer.mjs";
+import {
+  AuthEventName
+} from "./types.mjs";
+import { FetchTransport } from "./transports/fetch.mjs";
+import { RequestQueue } from "./queue.mjs";
+import { DeviceCollector } from "./device.mjs";
+import { DeviceInfoManager } from "./device-info-manager.mjs";
+import { LocalStorage, namespacedKey, NamespacedStorage, SessionStorage } from "./storage/index.mjs";
+import { OUTBOX_LOCK_NAME } from "./store/event-store.mjs";
+import { migrateLegacyStorage } from "./storage/migration.mjs";
+import {
+  DEFAULT_RELIABILITY_CONFIG,
+  resolveFixedDataConfig,
+  resolveReliabilityConfig
+} from "./config.mjs";
+import { ConfigManager } from "./config-manager.mjs";
+import { v7 as uuidv7 } from "uuid";
+import { isBlockedUserAgent } from "./utils/blocked-user-agents.mjs";
+import { hasWebLocks, withWebLock } from "./readers/web-lock.mjs";
+import { SDK_NAME, SDK_VERSION } from "./version.mjs";
+import { createLogger } from "./logger.mjs";
+import { PasswordManagerSampler } from "./utils/password-manager-sampler.mjs";
+import {
+  SEQ_STORAGE_KEY,
+  SESSION_CONTINUITY_KEY,
+  SESSION_STORAGE_KEY,
+  UUID_RE
+} from "./session-keys.mjs";
+var SDK_INFO = {
+  name: SDK_NAME,
+  version: SDK_VERSION
+};
+var INTEGRATION_VERSION_PATTERN = /^[0-9A-Za-z.+_-]{1,32}$/;
+function sdkInfo(integrationVersion, logger) {
+  if (integrationVersion === void 0) return SDK_INFO;
+  if (typeof integrationVersion === "string" && INTEGRATION_VERSION_PATTERN.test(integrationVersion)) {
+    return { ...SDK_INFO, integrationVersion };
+  }
+  logger.debug("Ignoring invalid integrationVersion (expected <= 32 chars of [0-9A-Za-z.+_-])");
+  return SDK_INFO;
+}
+var EXPERIMENTS_STORAGE_KEY = "cbo_experiments";
+var DATA_POLICY_STORAGE_KEY = "cbo_data_policy";
+var DATA_POLICY_MAX = 255;
+var EXPERIMENT_KEY_RE = /^[A-Za-z0-9_-]+$/;
+var EXPERIMENT_KEY_MAX = 128;
+var EXPERIMENT_VALUE_MAX = 256;
+var TELEMETRY_MESSAGE_MAX = 1e3;
+var MAX_SELF_TELEMETRY = 50;
+var SEQ_LOCK_NAME = "cbo_seq";
+var SESSION_ACTIVITY_WRITE_INTERVAL_MS = 1e3;
+var CorbadoTrackerCore = class _CorbadoTrackerCore {
+  /**
+   * @param options - Tracker options; `options.plugins` selects the optional features.
+   * @param plugins - Plugins installed before `options.plugins` (used by {@link CorbadoTracker}).
+   */
+  constructor(options, plugins = []) {
+    this.options = options;
+    this.options.debug = options.debug ?? false;
+    this.logger = options.logger ?? createLogger({ debug: this.options.debug });
+    const installed = plugins.concat(Array.isArray(options.plugins) ? options.plugins : []);
+    const localStorage = new LocalStorage(this.logger);
+    const sessionStorage = new SessionStorage(this.logger);
+    let custom;
+    this.eachPlugin(installed, (plugin) => {
+      if (plugin.storage) custom = plugin.storage(this.logger) || custom;
+    });
+    migrateLegacyStorage(options.projectId, localStorage, sessionStorage, custom?.engine, this.logger);
+    const namespace = options.projectId;
+    const scoped = (engine) => new NamespacedStorage(engine, namespace);
+    this.seqLockName = namespacedKey(SEQ_LOCK_NAME, namespace);
+    this.sessionStorage = scoped(sessionStorage);
+    this.persistentStorage = scoped(localStorage);
+    this.storage = scoped(custom?.engine ?? localStorage);
+    this.configOverrides = {
+      ...options.sdkConfig,
+      ...options.sdkConfig?.retry && { retry: { ...options.sdkConfig.retry } },
+      ...options.sdkConfig?.flushOnFlowTypeFinished && {
+        flushOnFlowTypeFinished: [...options.sdkConfig.flushOnFlowTypeFinished]
+      },
+      ...options.sdkConfig?.sourcePathQueryAllow && {
+        sourcePathQueryAllow: [...options.sdkConfig.sourcePathQueryAllow]
+      }
+    };
+    this.fixedData = resolveFixedDataConfig(options.fixedDataConfig);
+    if (this.fixedData) {
+      this.configOverrides.pmd = this.fixedData.pmd;
+    }
+    const completeOverride = Object.keys(DEFAULT_RELIABILITY_CONFIG).every(
+      (key) => this.configOverrides[key] !== void 0
+    ) && Object.keys(DEFAULT_RELIABILITY_CONFIG.retry).every(
+      (key) => this.configOverrides.retry?.[key] !== void 0
+    );
+    if (!completeOverride) {
+      this.configManager = new ConfigManager(
+        options.apiBaseUrl + (options.apiConfigPath ?? "/v1/observe/config") + "/" + options.projectId,
+        this.persistentStorage,
+        this.logger
+      );
+    }
+    const cachedConfig = this.configManager?.initialConfig;
+    this.config = resolveReliabilityConfig(cachedConfig, this.configOverrides);
+    if (!completeOverride && !cachedConfig && options.flushInterval != null && this.configOverrides.flushIntervalMs === void 0) {
+      this.config = { ...this.config, flushIntervalMs: options.flushInterval };
+    }
+    if (!completeOverride && !cachedConfig && options.deviceInfoCollectorTimeout != null && this.configOverrides.deviceInfoCollectorTimeoutMs === void 0) {
+      this.config = { ...this.config, deviceInfoCollectorTimeoutMs: options.deviceInfoCollectorTimeout };
+    }
+    if (options.apiBaseUrl !== "") {
+      if (!/^https?:\/\//.test(options.apiBaseUrl)) {
+        this.logger.critical(
+          `Invalid apiBaseUrl: URL must start with http:// or https:// (got: "${options.apiBaseUrl}")`
+        );
+        this.reportTelemetry("error", "invalid apiBaseUrl: missing http(s) scheme");
+      }
+      if (options.apiBaseUrl.endsWith("/")) {
+        this.logger.critical(`Invalid apiBaseUrl: URL must not have a trailing slash (got: "${options.apiBaseUrl}")`);
+        this.reportTelemetry("error", "invalid apiBaseUrl: trailing slash");
+      }
+    }
+    const url = options.apiBaseUrl + (options.apiEventPath ?? "/v1/observe/events") + "/" + options.projectId;
+    this.logger.debug(`Using API endpoint: ${url}`);
+    const transport = new FetchTransport({
+      logger: this.logger,
+      url
+    });
+    this.eachPlugin(installed, (plugin) => {
+      if (plugin.session) this.bridge = plugin.session(this) || this.bridge;
+      if (plugin.rawErrors) this.rawErrors = plugin.rawErrors;
+    });
+    if (options.fixedDataConfig?.crossOriginSession && !this.bridge) {
+      this.logger.warn("fixedDataConfig.crossOriginSession is ignored without the crossOriginSession() plugin");
+    }
+    this.sessionId = this.resolveSession();
+    this.queue = new RequestQueue(
+      this.logger,
+      transport,
+      this.sessionId,
+      sdkInfo(this.options.integrationVersion, this.logger),
+      {
+        debug: this.options.debug,
+        config: this.config,
+        requestConfig: false,
+        outboxLockName: namespacedKey(OUTBOX_LOCK_NAME, namespace),
+        getDataPolicy: () => this.dataPolicy,
+        getCrossOriginSession: (sessionId) => this.bridge?.meta(sessionId),
+        fixedData: this.fixedData !== void 0 || typeof __CBO_DATA_PMD__ === "boolean" || typeof __CBO_DATA_PRIVATE_MODE__ === "boolean",
+        beforeEventBatchSend: (events) => this.attachUndeliveredDeviceInfo(events),
+        // The queue is created before the device info manager; both are only called once it exists.
+        standaloneDeviceInfo: {
+          has: () => this.deviceInfoManager?.hasStandalone() ?? false,
+          take: () => this.deviceInfoManager?.takeStandalone()
+        }
+      },
+      this.persistentStorage
+    );
+    this.telemetryReady = true;
+    this.logger.setTelemetrySink?.((level, message) => this.reportTelemetry(level, message));
+    try {
+      this.getWindowObserver();
+    } catch (error) {
+      this.logger.error("Failed to attach page low-event observer", error);
+    }
+    if (typeof __CBO_DATA_PMD__ === "boolean" ? __CBO_DATA_PMD__ : this.fixedData?.pmd !== false) {
+      try {
+        this.passwordManagerSampler = this.isTrackingBlocked() ? void 0 : new PasswordManagerSampler(
+          this.logger,
+          () => typeof __CBO_DATA_PMD__ === "boolean" ? __CBO_DATA_PMD__ : this.config.pmd,
+          this.getWindowObserver()
+        );
+      } catch (error) {
+        this.logger.error("Failed to start password manager detection", error);
+      }
+    }
+    const bufferedTelemetry = this.pendingSelfTelemetry;
+    this.pendingSelfTelemetry = [];
+    for (const item of bufferedTelemetry) {
+      this.telemetry(item.level, item.message);
+    }
+    const deviceInfoCollector = new DeviceCollector(
+      this.logger,
+      this.storage,
+      custom?.source ?? "localstorage",
+      this.sessionStorage,
+      () => ({
+        timing: this.config.deviceInfoTiming
+      }),
+      // Timing entries carry raw millisecond values, so they go through the public telemetry path
+      // rather than reportTelemetry: the latter dedupes by exact message and is capped per load,
+      // where ever-changing messages would crowd out real error diagnostics.
+      (level, message) => this.telemetry(level, message),
+      this.fixedData?.privateMode ?? true
+    );
+    this.deviceCollector = deviceInfoCollector;
+    const deviceInfoDebounceTime = options.deviceInfoDebounceTime ?? 3e4;
+    this.deviceInfoManager = new DeviceInfoManager(
+      this.logger,
+      deviceInfoCollector,
+      Math.max(1, deviceInfoDebounceTime),
+      deviceInfoDebounceTime,
+      {
+        timing: () => this.config.deviceInfoTiming,
+        emit: (level, message) => this.telemetry(level, message)
+      },
+      () => this.queue.notifyDeviceInfo()
+    );
+    this.deviceInfoManager.start();
+    this.experiments = this.loadPersistedExperiments();
+    if (options.experiments) {
+      this.setExperiments(options.experiments);
+    }
+    this.dataPolicy = this.loadPersistedDataPolicy();
+    if (options.dataPolicy !== void 0) {
+      this.setDataPolicy(options.dataPolicy);
+    }
+    this.configManager?.start((config) => this.handleConfig(config));
+    this.eachPlugin(installed, (plugin) => {
+      if (plugin.setup) plugin.setup(this);
+    });
+  }
+  logger;
+  queue;
+  sessionId;
+  storage;
+  sessionStorage;
+  /** Dedicated localStorage engine for reliability state (config cache, outbox, continuity session, seq). */
+  persistentStorage;
+  /** Seq/continuity Web Lock name; project-scoped together with the storage keys it guards. */
+  seqLockName;
+  /** Current resolved policy. Continuity and persistence stay enabled once activated within a document. */
+  config;
+  configManager;
+  configOverrides;
+  /** Resolved `fixedDataConfig`; undefined when not given (server-driven data switches). */
+  fixedData;
+  deviceInfoManager;
+  deviceCollector;
+  /**
+   * Cached per-tab id stamped onto every event's meta (see {@link EventMeta.tabId}). Resolved
+   * lazily from the collector's sessionStorage-backed id; stable for the whole page lifetime.
+   */
+  eventTabId;
+  seq = 0;
+  /**
+   * When the continuity record's `lastActiveAt` was last persisted. Throttles that write inside the
+   * seq critical section (see {@link SESSION_ACTIVITY_WRITE_INTERVAL_MS}). 0 = not written yet on
+   * this load, so the first allocation always persists.
+   */
+  lastActivityWriteAt = 0;
+  /** Persistent experiment assignments (experiment key → variant), attached to every produced event. */
+  experiments = {};
+  /**
+   * Persistent data policy code, stamped into every batch's `meta.dataPolicy` once set. Never
+   * cleared (only overwritten): it survives reloads, session rotation, resetSession and destroy.
+   */
+  dataPolicy;
+  /** Self-instrumentation state: re-entrancy guard, readiness, per-load dedupe, and pre-queue buffer. */
+  telemetryReporting = false;
+  telemetryReady = false;
+  reportedTelemetryKeys = /* @__PURE__ */ new Set();
+  pendingSelfTelemetry = [];
+  windowObserver;
+  passwordManagerSampler;
+  /** Session reconciliation of a plugin (the cross-origin session); undefined when none is installed. */
+  bridge;
+  /** Raw-error serializer of a plugin; undefined = operation step errors drop `rawError`. */
+  rawErrors;
+  /** @internal Shared passive page observation and per-operation context registration. */
+  getWindowObserver() {
+    return this.windowObserver ??= new SharedWindowObserver(
+      this.logger,
+      (low, sessionId) => this.enqueueLowEvent(low, sessionId),
+      () => this.lowEventFlushKeepalive()
+    );
+  }
+  /** Runs `install` per plugin; a missing or throwing plugin is logged and skipped (never throws). */
+  eachPlugin(plugins, install) {
+    for (const plugin of plugins) {
+      try {
+        if (plugin) install(plugin);
+      } catch (error) {
+        this.logger.error("Failed to install tracker plugin", error);
+      }
+    }
+  }
+  /**
+   * Whether this tracker is the full {@link CorbadoTracker} (created by {@link init} or its constructor).
+   * @internal
+   */
+  isFullTracker() {
+    return false;
+  }
+  /** Apply init overrides on every refresh; continuity and persistence only activate within a document. */
+  handleConfig(config) {
+    const next = resolveReliabilityConfig(config, this.configOverrides);
+    next.sessionContinuity ||= this.config.sessionContinuity;
+    next.durableOutbox ||= this.config.durableOutbox;
+    this.config = next;
+    this.queue.updateConfig(this.config);
+  }
+  /**
+   * Returns the logger used by this tracker.
+   * @internal
+   */
+  getLogger() {
+    return this.logger;
+  }
+  applicationTag() {
+    if (this.options.applicationId) {
+      return { applicationId: this.options.applicationId.toLowerCase() };
+    }
+    return {};
+  }
+  // --- Experiments ---
+  /**
+   * Register several experiment assignments at once (experiment key → variant). Additive: existing
+   * assignments for other keys are kept. See {@link CorbadoTracker.setExperiment}.
+   *
+   * Never throws: invalid input is ignored with a debug log.
+   */
+  setExperiments(assignments) {
+    try {
+      if (!assignments || typeof assignments !== "object") {
+        return;
+      }
+      let changed = false;
+      for (const [key, variant] of Object.entries(assignments)) {
+        if (!_CorbadoTrackerCore.isValidExperimentKey(key) || !_CorbadoTrackerCore.isValidExperimentVariant(variant)) {
+          this.logger.debug(`Ignoring invalid experiment assignment "${String(key)}"`);
+          continue;
+        }
+        if (this.experiments[key] !== variant) {
+          this.experiments[key] = variant;
+          changed = true;
+        }
+      }
+      if (changed) {
+        this.persistExperiments();
+      }
+    } catch (error) {
+      this.logger.error("Failed to set experiments", error);
+    }
+  }
+  /** Returns a copy of the currently active experiment assignments. */
+  getExperiments() {
+    return { ...this.experiments };
+  }
+  /**
+   * Returns the currently active public SDK configuration, including live updates.
+   *
+   * @returns A frozen snapshot, created fresh on every call.
+   */
+  /** @internal Project-scoped localStorage used by operation helpers (e.g. email-link continuity). */
+  getPersistentStorage() {
+    return this.persistentStorage;
+  }
+  getSdkConfig() {
+    return Object.freeze({
+      version: this.config.version,
+      aap: this.config.aap,
+      rawErrors: this.config.rawErrors
+    });
+  }
+  // --- Data policy ---
+  /**
+   * Set the data policy code for this tracker (e.g. `setDataPolicy(1)` once the user agreed to
+   * extended processing; `setDataPolicy(0)` to return to the project default). Codes are
+   * project-scoped non-negative integers (0..255) selecting a policy configured in Corbado; they
+   * carry no ordering.
+   *
+   * The code is persisted (localStorage, project-scoped) and sent as `meta.dataPolicy` on every
+   * subsequent batch, across reloads and session rotation. It is never cleared, only overwritten.
+   * The server records the latest code it receives for a session (last write wins). Invalid codes
+   * are ignored with a debug log; never throws.
+   */
+  setDataPolicy(code) {
+    try {
+      if (!_CorbadoTrackerCore.isValidDataPolicy(code)) {
+        this.logger.debug(`Ignoring invalid data policy code "${String(code)}"`);
+        return;
+      }
+      if (this.dataPolicy !== code) {
+        this.dataPolicy = code;
+        this.persistDataPolicy();
+      }
+    } catch (error) {
+      this.logger.error("Failed to set data policy", error);
+    }
+  }
+  /** Returns the current data policy code, or undefined when none has ever been set. */
+  getDataPolicy() {
+    return this.dataPolicy;
+  }
+  static isValidDataPolicy(code) {
+    return typeof code === "number" && Number.isInteger(code) && code >= 0 && code <= DATA_POLICY_MAX;
+  }
+  loadPersistedDataPolicy() {
+    try {
+      const stored = this.persistentStorage.getItem(DATA_POLICY_STORAGE_KEY);
+      return _CorbadoTrackerCore.isValidDataPolicy(stored) ? stored : void 0;
+    } catch (error) {
+      this.logger.debug("Failed to load persisted data policy", error);
+      return void 0;
+    }
+  }
+  persistDataPolicy() {
+    try {
+      if (this.dataPolicy === void 0) {
+        return;
+      }
+      this.persistentStorage.setItem(DATA_POLICY_STORAGE_KEY, this.dataPolicy);
+    } catch (error) {
+      this.logger.debug("Failed to persist data policy", error);
+    }
+  }
+  static isValidExperimentKey(key) {
+    return typeof key === "string" && key.length > 0 && key.length <= EXPERIMENT_KEY_MAX && EXPERIMENT_KEY_RE.test(key);
+  }
+  static isValidExperimentVariant(variant) {
+    return typeof variant === "string" && variant.length > 0 && variant.length <= EXPERIMENT_VALUE_MAX;
+  }
+  loadPersistedExperiments() {
+    try {
+      const stored = this.persistentStorage.getItem(EXPERIMENTS_STORAGE_KEY);
+      if (!stored || typeof stored !== "object") {
+        return {};
+      }
+      const cleaned = {};
+      for (const [key, variant] of Object.entries(stored)) {
+        if (_CorbadoTrackerCore.isValidExperimentKey(key) && _CorbadoTrackerCore.isValidExperimentVariant(variant)) {
+          cleaned[key] = variant;
+        }
+      }
+      return cleaned;
+    } catch (error) {
+      this.logger.debug("Failed to load persisted experiments", error);
+      return {};
+    }
+  }
+  persistExperiments() {
+    try {
+      this.persistentStorage.setItem(EXPERIMENTS_STORAGE_KEY, this.experiments);
+    } catch (error) {
+      this.logger.debug("Failed to persist experiments", error);
+    }
+  }
+  /**
+   * Resolves the experiments to attach to one event: the persistent assignments with any per-call
+   * override merged on top. Returns undefined when there are none (so the field is omitted).
+   */
+  resolveExperiments(perCall) {
+    const merged = { ...this.experiments };
+    if (perCall && typeof perCall === "object") {
+      for (const [key, variant] of Object.entries(perCall)) {
+        if (_CorbadoTrackerCore.isValidExperimentKey(key) && _CorbadoTrackerCore.isValidExperimentVariant(variant)) {
+          merged[key] = variant;
+        }
+      }
+    }
+    return Object.keys(merged).length > 0 ? merged : void 0;
+  }
+  isTrackingBlocked() {
+    if (typeof navigator === "undefined") {
+      return false;
+    }
+    return isBlockedUserAgent(
+      readUserAgent({
+        key: "browser-api:sdk.blocked-user-agent",
+        title: "User agent check for crawlers and bots",
+        accessNote: "navigator.userAgent, matched against a list of crawler and bot patterns",
+        group: "Observe SDK state",
+        origin: "observe-external",
+        fields: [
+          {
+            path: "result",
+            label: "Whether the browser looks like a bot",
+            exposure: "computed",
+            transform: { note: "matched against the blocked user-agent list; only the boolean is used (tracking off)" }
+          }
+        ]
+      })
+    );
+  }
+  /**
+   * Resolve the session of this load: locally ({@link resolveSessionId}), or through the session bridge
+   * of a plugin (cross-origin session) when one is installed. Used at boot and by the recovery in
+   * `getSessionId`.
+   */
+  resolveSession() {
+    return this.bridge ? this.bridge.resolve() : this.resolveSessionId();
+  }
+  resolveSessionId() {
+    try {
+      if (this.config.sessionContinuity) {
+        return this.getContinuitySessionId();
+      }
+      const now = Date.now();
+      const stored = this.readPerTabSession();
+      if (stored && now - stored.lastActiveAt < this.perTabInactivityMs(stored)) {
+        this.persistPerTabSession(stored.id, now);
+        this.seq = 0;
+        return stored.id;
+      }
+      const newSessionId = uuidv7();
+      this.persistPerTabSession(newSessionId, now);
+      this.seq = 0;
+      this.logger.debug("Created session id", newSessionId);
+      return newSessionId;
+    } catch (error) {
+      this.logger.error("Failed to get session id", error);
+      this.reportTelemetry("error", "failed to get session id");
+      return "";
+    }
+  }
+  /**
+   * Resolve the session id from localStorage so it survives reloads and is shared across tabs of the
+   * same browser. Rotates after `config.sessionInactivityMs` of inactivity (server-controlled,
+   * evaluated at boot), resetting the seq counter.
+   *
+   * Inactivity rotation happens at boot only, here and on the per-tab path {@link resolveSessionId}
+   * takes without continuity. Boot is chosen on an assumption, not a guarantee: that a load
+   * re-announces its flow, so the fresh session id gets a classifiable flow. That holds where a
+   * flow is opened per load. Where one is opened once and carried across loads it does not, and a
+   * boot rotation splits that flow — such a project needs a window long enough to span the journey.
+   * Mid-page the assumption is not even available: nothing re-announces between two tracked events,
+   * so rotating there would leave the started flow unfinished in the old session and the remaining
+   * events without a flow start in the new one — one gap counted as a drop-off, one completion
+   * counted as nothing. `nextSeq` therefore never rotates on inactivity, on either path.
+   */
+  getContinuitySessionId() {
+    const now = Date.now();
+    const existing = this.persistentStorage.getItem(SESSION_CONTINUITY_KEY);
+    if (existing?.id && now - existing.lastActiveAt < this.config.sessionInactivityMs) {
+      this.persistContinuitySession(existing.id, now);
+      this.seq = this.persistentStorage.getItem(SEQ_STORAGE_KEY) ?? 0;
+      return existing.id;
+    }
+    if (!existing?.id) {
+      const perTab = this.readPerTabSession();
+      if (perTab && now - perTab.lastActiveAt < this.config.sessionInactivityMs) {
+        this.persistContinuitySession(perTab.id, now);
+        this.persistentStorage.setItem(SEQ_STORAGE_KEY, 0);
+        this.seq = 0;
+        this.logger.debug("Adopted per-tab session id as continuity session", perTab.id);
+        return perTab.id;
+      }
+    }
+    const newSessionId = uuidv7();
+    this.persistContinuitySession(newSessionId, now);
+    this.persistentStorage.setItem(SEQ_STORAGE_KEY, 0);
+    this.seq = 0;
+    this.logger.debug("Created continuity session id", newSessionId);
+    return newSessionId;
+  }
+  /**
+   * Persist the continuity record and remember when, so the throttled refresh in the seq critical
+   * section measures from the last write that actually happened — whoever made it.
+   */
+  persistContinuitySession(id, now) {
+    this.lastActivityWriteAt = now;
+    this.persistentStorage.setItem(SESSION_CONTINUITY_KEY, { id, lastActiveAt: now });
+  }
+  /**
+   * Read the per-tab session record. A bare string is the format that predates dating: it carries no
+   * `lastActiveAt`, so its window can only start on the load that reads it. That load rewrites it in
+   * the dated shape, so a tab converts once and ages normally from then on, and the case drains as
+   * the rollout replaces the bundles that write it.
+   */
+  readPerTabSession() {
+    const stored = this.sessionStorage.getItem(SESSION_STORAGE_KEY);
+    if (!stored) {
+      return void 0;
+    }
+    if (typeof stored === "string") {
+      return UUID_RE.test(stored) ? { id: stored, lastActiveAt: Date.now() } : void 0;
+    }
+    if (typeof stored.lastActiveAt !== "number") {
+      return void 0;
+    }
+    return UUID_RE.test(stored.id) ? stored : void 0;
+  }
+  /**
+   * Persist the per-tab record and remember when, sharing the throttle bookkeeping with the
+   * continuity record — a load resolves its session on one path or the other, never both.
+   *
+   * An explicit timeout override or server config stamps the window. Otherwise carry forward what
+   * the tab already knows, so a defaults boot does not replace a previously configured threshold.
+   */
+  persistPerTabSession(id, now) {
+    this.lastActivityWriteAt = now;
+    const inactivityMs = this.configOverrides.sessionInactivityMs !== void 0 || this.config.version ? this.config.sessionInactivityMs : this.readPerTabSession()?.inactivityMs;
+    this.sessionStorage.setItem(SESSION_STORAGE_KEY, {
+      id,
+      lastActiveAt: now,
+      ...inactivityMs === void 0 ? {} : { inactivityMs }
+    });
+  }
+  /** Explicit init timeout wins; otherwise retain the window a prior configured load recorded. */
+  perTabInactivityMs(stored) {
+    return this.configOverrides.sessionInactivityMs !== void 0 ? this.config.sessionInactivityMs : stored.inactivityMs ?? this.config.sessionInactivityMs;
+  }
+  /**
+   * Return the next sequence number. With session continuity the counter is persisted so ordering
+   * survives reloads/redirects; the read-increment-write runs under a cross-tab Web Lock
+   * ({@link SEQ_LOCK_NAME}) so two tabs sharing the session cannot allocate the same seq (where Web
+   * Locks are unavailable or exceed the configured timeout it degrades to the historical best-effort merge).
+   * Lock grants are FIFO, so seq order matches `track()` call order within a tab. Tracking also keeps the
+   * continuity session's `lastActiveAt` fresh (throttled, see {@link SESSION_ACTIVITY_WRITE_INTERVAL_MS}),
+   * so the window the NEXT boot evaluates measures real user
+   * inactivity instead of time-since-page-load (a long-lived active tab must not rotate the session
+   * on the next reload). It never rotates the session itself: the inactivity window is evaluated at
+   * boot only ({@link getContinuitySessionId} documents why). Consequence: while a page is never
+   * reloaded — foreground idle, bfcache restore, long-lived SPA tab — a session can outlive
+   * `sessionInactivityMs`. That inflates flow durations but keeps flow counts correct, which is the
+   * better half of the trade. An empty store while this load already has a session id means
+   * persistence is failing (or was cleared); the in-memory id is reused then — never re-minted — so
+   * a broken store degrades to one session per page load instead of one session per event.
+   */
+  nextSeq() {
+    if (!this.config.sessionContinuity) {
+      const now = Date.now();
+      if (this.sessionId && now - this.lastActivityWriteAt >= SESSION_ACTIVITY_WRITE_INTERVAL_MS) {
+        this.persistPerTabSession(this.sessionId, now);
+      }
+      const current = this.bridge ? this.bridge.claim(this.sessionId, this.seq, now) : this.seq;
+      this.seq = current + 1;
+      return current;
+    }
+    const allocate = () => {
+      const now = Date.now();
+      const storedSession = this.persistentStorage.getItem(SESSION_CONTINUITY_KEY);
+      let sessionChanged = false;
+      if (!storedSession?.id && this.sessionId) {
+        this.persistContinuitySession(this.sessionId, now);
+      } else if (!storedSession?.id) {
+        const newSessionId = uuidv7();
+        this.persistContinuitySession(newSessionId, now);
+        this.persistentStorage.setItem(SEQ_STORAGE_KEY, 0);
+        this.sessionId = newSessionId;
+        this.queue.setSessionId(newSessionId);
+        this.seq = 0;
+        sessionChanged = true;
+      } else {
+        if (now - this.lastActivityWriteAt >= SESSION_ACTIVITY_WRITE_INTERVAL_MS) {
+          this.persistContinuitySession(storedSession.id, now);
+        }
+        if (storedSession.id !== this.sessionId) {
+          this.sessionId = storedSession.id;
+          this.queue.setSessionId(storedSession.id);
+          sessionChanged = true;
+        }
+      }
+      const stored = this.persistentStorage.getItem(SEQ_STORAGE_KEY);
+      if (sessionChanged) {
+        this.seq = typeof stored === "number" ? stored : 0;
+      }
+      let current = typeof stored === "number" && stored > this.seq ? stored : this.seq;
+      if (this.bridge) {
+        current = this.bridge.claim(this.sessionId, current, now);
+      }
+      this.seq = current + 1;
+      this.persistentStorage.setItem(SEQ_STORAGE_KEY, this.seq);
+      return current;
+    };
+    const timeoutMs = this.config.seqLockTimeoutMs;
+    if (timeoutMs === 0 || !hasWebLocks({
+      key: "browser-api:sdk.web-locks",
+      title: "Coordination of Observe data across open tabs",
+      accessNote: "Web Locks API (navigator.locks) on Observe's own lock names",
+      group: "Observe SDK state",
+      origin: "observe-internal",
+      fields: [
+        {
+          path: "available",
+          label: "Whether the browser supports tab coordination",
+          exposure: "enum",
+          transform: { values: [true, false] }
+        }
+      ]
+    })) {
+      return allocate();
+    }
+    return withWebLock(
+      {
+        key: "browser-api:sdk.web-locks",
+        title: "Coordination of Observe data across open tabs",
+        accessNote: "Web Locks API (navigator.locks) on Observe's own lock names",
+        group: "Observe SDK state",
+        origin: "observe-internal",
+        fields: [
+          {
+            path: "result",
+            label: "Coordination between open tabs",
+            exposure: "none",
+            transform: { note: "own cbo_* lock names; serializes the SDK's storage updates across tabs" }
+          }
+        ]
+      },
+      this.seqLockName,
+      allocate,
+      {
+        timeoutMs,
+        onTimeout: () => {
+          this.logger.warn(`Sequence Web Lock acquisition timed out after ${timeoutMs}ms; using fallback`);
+          this.reportTelemetry("info", `seq web lock timeout; using fallback, ${timeoutMs}ms`);
+        }
+      }
+    );
+  }
+  resolveTrackingSourcePath() {
+    if (typeof window === "undefined") {
+      return void 0;
+    }
+    return readSourcePath(
+      {
+        key: "page:location.source-path",
+        title: "Page path and allowed query parameters",
+        accessNote: "location.pathname and location.search; the query is reduced by the sourcePathQuery policy inside the reader (trackingSourcePath)",
+        group: "Page",
+        origin: "observe-external",
+        fields: [
+          { path: "url.path", label: "Page path", exposure: "raw" },
+          {
+            path: "url.query",
+            label: "Page address parameters (allowed ones only)",
+            exposure: "redacted",
+            transform: { note: "sourcePathQuery 'allowlist': values of non-allowlisted keys become '*'; 'all': raw" }
+          }
+        ]
+      },
+      this.config.sourcePathQuery,
+      this.config.sourcePathQueryAllow
+    );
+  }
+  /**
+   * Per-tab id for event meta, cached after the first successful resolution: the id is
+   * sessionStorage-backed and stable for the whole page lifetime.
+   */
+  resolveEventTabId() {
+    if (this.eventTabId === void 0) {
+      this.eventTabId = this.deviceCollector.getTabId();
+    }
+    return this.eventTabId;
+  }
+  /** @internal */
+  trackSubflowStarted(subflowType, data, options, eventId) {
+    const wrappedData = {
+      subflowType,
+      ...data
+    };
+    void this.track(
+      AuthEventName.SubflowStarted,
+      wrappedData,
+      options?.userReference,
+      void 0,
+      void 0,
+      options?.explicitTimestamp,
+      options?.experiments,
+      {
+        id: eventId,
+        subflowStartEventId: options?.subflowStartEventId,
+        sessionId: options?.captureSessionId,
+        initiator: options?.initiator
+      }
+    );
+  }
+  /** @internal */
+  trackSubflowTrigger(subflowType, data, options) {
+    const wrappedData = {
+      subflowType,
+      ...data
+    };
+    void this.track(
+      AuthEventName.SubflowTrigger,
+      wrappedData,
+      options?.userReference,
+      void 0,
+      void 0,
+      options?.explicitTimestamp,
+      options?.experiments,
+      {
+        subflowStartEventId: options?.subflowStartEventId,
+        sessionId: options?.captureSessionId,
+        initiator: options?.initiator
+      }
+    );
+  }
+  /** @internal */
+  trackSubflowStepStarted(subflowType, stepName, data, options, ignoreAsInteraction) {
+    const wrappedData = {
+      subflowType,
+      stepName,
+      stepData: data,
+      identifier: options?.identifier,
+      ignoreAsInteraction
+    };
+    void this.track(
+      AuthEventName.SubflowStepStarted,
+      wrappedData,
+      options?.userReference,
+      void 0,
+      void 0,
+      options?.explicitTimestamp,
+      options?.experiments,
+      {
+        subflowStartEventId: options?.subflowStartEventId,
+        sessionId: options?.captureSessionId,
+        initiator: options?.initiator
+      }
+    );
+  }
+  /** @internal */
+  trackSubflowStepFinished(subflowType, stepName, data, options) {
+    const wrappedData = {
+      subflowType,
+      stepName,
+      stepData: data,
+      identifier: options?.identifier
+    };
+    void this.track(
+      AuthEventName.SubflowStepFinished,
+      wrappedData,
+      options?.userReference,
+      void 0,
+      void 0,
+      options?.explicitTimestamp,
+      options?.experiments,
+      {
+        subflowStartEventId: options?.subflowStartEventId,
+        sessionId: options?.captureSessionId,
+        initiator: options?.initiator
+      }
+    );
+  }
+  /** @internal */
+  trackSubflowStepError(subflowType, stepName, data, options) {
+    const wrappedData = {
+      subflowType,
+      stepName,
+      stepData: data,
+      identifier: options?.identifier
+    };
+    void this.track(
+      AuthEventName.SubflowStepError,
+      wrappedData,
+      options?.userReference,
+      void 0,
+      void 0,
+      options?.explicitTimestamp,
+      options?.experiments,
+      {
+        subflowStartEventId: options?.subflowStartEventId,
+        sessionId: options?.captureSessionId,
+        initiator: options?.initiator
+      }
+    );
+  }
+  /**
+   * Error situations:
+   *  - Blocked user agent (see `isBlockedUserAgent`): skip with a debug log and return
+   *  - Any error before the event is enqueued (e.g. `JSON.stringify` in debug logging, `queue.enqueue`): log `Failed to process event "<name>" before enqueue`
+   *
+   * @internal
+   */
+  async track(name, data, userReference, tags, contexts, explicitTimestamp, experiments, capture) {
+    try {
+      if (this.isTrackingBlocked()) {
+        this.logger.debug(`Skipping event "${name}" for blocked user agent.`);
+        return;
+      }
+      if (name === AuthEventName.FlowFinished || name === AuthEventName.FlowAutoFinished || name === AuthEventName.FlowReset) {
+        this.windowObserver?.flushInputs();
+      }
+      const timestamp = explicitTimestamp ?? Date.now();
+      const capturedId = capture?.id ?? uuidv7();
+      const capturedSessionId = capture?.sessionId ?? this.sessionId;
+      const nextSeq = this.nextSeq();
+      const seq = typeof nextSeq === "number" ? nextSeq : await nextSeq;
+      const trackingSourcePath = this.resolveTrackingSourcePath();
+      const event = {
+        type: "predefined",
+        name,
+        id: capturedId,
+        timestamp,
+        seq,
+        data,
+        user: userReference,
+        contexts,
+        tags,
+        experiments: this.resolveExperiments(experiments),
+        meta: {
+          captureVersion: 1,
+          pageId: getCapturePageId(),
+          initiator: capture?.initiator,
+          trackingSourcePath: trackingSourcePath ?? "",
+          subflowStartEventId: capture?.subflowStartEventId,
+          tabId: this.resolveEventTabId()
+        }
+      };
+      const deviceInfo = this.deviceInfoManager.getForEvent();
+      if (deviceInfo) {
+        event.deviceInfo = deviceInfo;
+      }
+      this.logger.debug(`Track: ${name}`, JSON.stringify(event, null, 2));
+      const passwordManagers = this.passwordManagerSampler?.takeReport(capturedSessionId);
+      if (passwordManagers) {
+        event.passwordManagers = passwordManagers;
+      }
+      this.queue.enqueue(event, capturedSessionId);
+    } catch (error) {
+      this.logger.error(`Failed to process event "${name}" before enqueue`, error);
+      this.reportTelemetry("error", `failed to process event "${name}" before enqueue`);
+    }
+  }
+  // --- Typed Tracking Methods ---
+  /**
+   * Track when an authentication flow (or flow selection screen) becomes visible.
+   *
+   * @remarks
+   * Call this once when the user first enters an auth touchpoint (for example account login,
+   * checkout login, or account recovery). If users can choose between multiple flows
+   * (such as login vs signup), pass `flowNames` and optionally `defaultFlowName`.
+   *
+   * The returned handle can attach identity after completion with `await flow.enrich({ userId })`.
+   * Enrichment requires a backend supporting explicit event targeting.
+   *
+   * @param data - Flow metadata, including one flow (`flowName`) or multiple candidates (`flowNames`).
+   * @param tags - Optional key-value tags for filtering and segmentation.
+   * @param experiments - Optional per-call experiment overrides.
+   * @param contexts - Optional structured event context (e.g. technical metadata that is not an
+   *   analytical dimension). Written to the event's `contexts` field verbatim.
+   * @param options - Optional `explicitTimestamp` (epoch ms) when the flow became visible earlier than
+   *   this call, e.g. because an integration confirms a screen only after it stayed up for a while.
+   *
+   * @example
+   * ```typescript
+   * tracker.flowStarted({
+   *   flowNames: ["login", "signup"],
+   *   defaultFlowName: "login",
+   *   touchpoint: "account",
+   * });
+   * ```
+   */
+  flowStarted(data, tags, experiments, contexts, options) {
+    try {
+      const targetEventId = uuidv7();
+      const sessionId = this.sessionId;
+      const effectiveTags = { ...this.options.defaultTags, ...this.applicationTag(), ...tags };
+      void this.track(
+        AuthEventName.FlowStarted,
+        data,
+        void 0,
+        effectiveTags,
+        contexts,
+        options?.explicitTimestamp,
+        experiments,
+        {
+          id: targetEventId,
+          sessionId
+        }
+      );
+      return this.flowHandle(targetEventId, sessionId);
+    } catch (error) {
+      this.logger.warn("Failed to start flow", error);
+      return { enrich: async () => {
+      } };
+    }
+  }
+  /**
+   * Track when the user commits to a specific flow.
+   *
+   * @remarks
+   * Use this after presenting alternatives and once you know which path the user takes
+   * (for example when identifier checks route to login vs signup).
+   *
+   * @param data - Selected flow name.
+   * @param tags - Optional key-value tags for filtering and segmentation.
+   *
+   * @example
+   * ```typescript
+   * tracker.flowDecided({flowName: "signup"});
+   * ```
+   */
+  flowDecided(data, tags, experiments) {
+    void this.track(AuthEventName.FlowDecided, data, void 0, tags, void 0, void 0, experiments);
+  }
+  /**
+   * Track when a flow successfully completes.
+   *
+   * @remarks
+   * Fire this when the user has finished the target flow end-to-end, such as completed login,
+   * signup, or recovery. Record identity with `setUser()` while the flow is active,
+   * or enrich it after completion through the handle returned by `flowStarted()` or by this call.
+   *
+   * The returned handle targets the flow this event finished, so identity learned only after
+   * completion — for example from a profile request that follows account creation — can be
+   * attached with `await finished.enrich({ userId })` even on a page that never saw the flow start.
+   * Enrichment requires a backend supporting explicit flow-event targeting.
+   *
+   * Legacy identity fields in `data` remain supported but are deprecated.
+   *
+   * @param data - Finished flow name, optional explicit outcome, and deprecated user reference fields.
+   * @param tags - Optional key-value tags for filtering and segmentation.
+   *
+   * @example
+   * ```typescript
+   * const finished = tracker.flowFinished({ flowName: "signup" });
+   * const userId = await hashUserId(createdAccountId);
+   * await finished.enrich({ userId });
+   * ```
+   */
+  flowFinished(data, tags, experiments) {
+    try {
+      const { userId, identifier, ...dataOut } = data;
+      const userReference = { userId, identifier };
+      const targetEventId = uuidv7();
+      const sessionId = this.sessionId;
+      void this.track(AuthEventName.FlowFinished, dataOut, userReference, tags, void 0, void 0, experiments, {
+        id: targetEventId,
+        sessionId
+      });
+      return this.flowHandle(targetEventId, sessionId);
+    } catch (error) {
+      this.logger.warn("Failed to finish flow", error);
+      return { enrich: async () => {
+      } };
+    }
+  }
+  /** Emits `flow_enriched` against an explicit target, in the session that emitted the target. */
+  flowHandle(targetEventId, sessionId) {
+    return {
+      enrich: async (user) => {
+        try {
+          await this.track(
+            AuthEventName.FlowEnriched,
+            { targetEventId },
+            { ...user },
+            void 0,
+            void 0,
+            void 0,
+            void 0,
+            { sessionId }
+          );
+        } catch (error) {
+          this.logger.warn("Failed to enrich flow", error);
+        }
+      }
+    };
+  }
+  /**
+   * Track when an in-progress flow is reset and restarted.
+   *
+   * @remarks
+   * Use this when users abandon the current path and return to the beginning of the same flow,
+   * for example after switching account/identifier and reopening the first step.
+   *
+   * @param data - Flow name being reset.
+   * @param tags - Optional key-value tags for filtering and segmentation.
+   *
+   * @example
+   * ```typescript
+   * tracker.flowReset({flowName: "login"});
+   * ```
+   */
+  flowReset(data, tags, experiments) {
+    void this.track(AuthEventName.FlowReset, data, void 0, tags, void 0, void 0, experiments);
+  }
+  /**
+   * Track when a flow is considered finished because another flow finished it implicitly.
+   *
+   * @remarks
+   * Use this for automatic completions where no separate explicit finish action happens in the
+   * current flow. Set `flowName` to the auto-finished flow and `finishedByFlowName` to the flow
+   * that caused it. Record identity with `setUser()` while the intended flow is still
+   * current, before it is auto-finished.
+   *
+   * Legacy identity fields in `data` remain supported but are deprecated.
+   *
+   * @param data - Auto-finished flow, finishing flow, and deprecated user reference fields.
+   * @param tags - Optional key-value tags for filtering and segmentation.
+   *
+   * @example
+   * ```typescript
+   * tracker.flowAutoFinished({
+   *   flowName: "signup",
+   *   finishedByFlowName: "login",
+   * });
+   * ```
+   */
+  flowAutoFinished(data, tags, experiments) {
+    const { userId, identifier, ...dataOut } = data;
+    const userReference = { userId, identifier };
+    void this.track(AuthEventName.FlowAutoFinished, dataOut, userReference, tags, void 0, void 0, experiments);
+  }
+  /**
+   * Track when you present authentication method choices to the user.
+   *
+   * @remarks
+   * Use this whenever a decision point is shown with a concrete method set, such as
+   * identifier entry options (`d1`) or post-identifier options (`d3`). Set
+   * `explicitDecisionValue` when the options are re-offered after a user action and you want
+   * to capture what triggered that transition.
+   *
+   * @param data - Decision identifier, offered options, and optional transition reason.
+   * @param tags - Optional key-value tags for filtering and segmentation.
+   * @param experiments - Optional per-call experiment assignments.
+   * @param options - Optional explicit event timestamp.
+   *
+   * @example
+   * ```typescript
+   * tracker.authMethodsDecisionStarted({
+   *   decisionName: "d3",
+   *   options: ["passkey", "social-google", "password", "reset-flow"],
+   * });
+   * ```
+   */
+  authMethodsDecisionStarted(data, tags, experiments, options) {
+    void this.track(
+      AuthEventName.AuthMethodDecisionStarted,
+      data,
+      void 0,
+      tags,
+      void 0,
+      options?.explicitTimestamp,
+      experiments
+    );
+  }
+  authMethodsDecisionFinished(data, tags, experiments) {
+    void this.track(AuthEventName.AuthMethodDecisionFinished, data, void 0, tags, void 0, void 0, experiments);
+  }
+  /**
+   * Enqueue a "low" event (granular DOM/window/visualviewport/PWM signal) for the current session.
+   *
+   * @remarks
+   * Low events are sent in the `lows` array of the events endpoint payload, alongside any
+   * pending typed events. Blocked user agents are skipped silently.
+   *
+   * @internal
+   */
+  enqueueLowEvent(low, capturedSessionId) {
+    try {
+      if (this.isTrackingBlocked()) {
+        this.logger.debug(`Skipping low event "${low.lowType}" for blocked user agent.`);
+        return;
+      }
+      this.queue.enqueueLow(
+        {
+          ...low,
+          captureSeq: low.captureSeq ?? reserveCaptureSeq(),
+          captureVersion: 1,
+          pageId: low.pageId ?? getCapturePageId()
+        },
+        capturedSessionId
+      );
+    } catch (error) {
+      this.logger.error(`Failed to process low event "${low.lowType}" before enqueue`, error);
+    }
+  }
+  /**
+   * Record a diagnostic telemetry entry (a `level` + free-form `message`) for the current session.
+   *
+   * @remarks
+   * Telemetry is delivered in the `telemetry` array of the events endpoint payload, tied to the same
+   * session, and is never classified as an auth-flow event. By default a telemetry entry piggybacks
+   * the next normal flush (it does not trigger one on its own); this is server-controlled. Collection
+   * can be turned off server-side via the `telemetry` config flag. Blocked user agents are skipped.
+   *
+   * The message is truncated to {@link TELEMETRY_MESSAGE_MAX} characters. Never pass credentials or
+   * PII — telemetry is for diagnostics only. Like all SDK entry points, this never throws.
+   */
+  telemetry(level, message) {
+    try {
+      if (this.isTrackingBlocked()) {
+        this.logger.debug("Skipping telemetry for blocked user agent.");
+        return;
+      }
+      const text = typeof message === "string" ? message : String(message);
+      if (text.length === 0) {
+        return;
+      }
+      const entry = {
+        id: uuidv7(),
+        level,
+        message: text.length > TELEMETRY_MESSAGE_MAX ? text.slice(0, TELEMETRY_MESSAGE_MAX) : text,
+        ts: Date.now()
+      };
+      this.queue.enqueueTelemetry(entry);
+    } catch (error) {
+      this.logger.error("Failed to process telemetry before enqueue", error);
+    }
+  }
+  /**
+   * Queue hook run right before an event batch is sent: a device info snapshot that no event carried
+   * yet (typically the fast snapshot after a burst of events at page load, or the privateMode update)
+   * rides the first event of this page in the batch that has none. Events of other pages (outbox
+   * replays) are never touched. A snapshot no event can carry goes as the batch's request-level device
+   * info instead (queue option `standaloneDeviceInfo`).
+   *
+   * Error situations:
+   *  - Any error: log "Failed to attach device info to batch" and send the batch unchanged
+   */
+  attachUndeliveredDeviceInfo(events) {
+    try {
+      const manager = this.deviceInfoManager;
+      if (!manager?.hasUndelivered()) {
+        return;
+      }
+      const pageId = getCapturePageId();
+      const target = events.find((event) => event.meta?.pageId === pageId && !event.deviceInfo);
+      if (target) {
+        target.deviceInfo = manager.takeUndelivered();
+      }
+    } catch (error) {
+      this.logger.error("Failed to attach device info to batch", error);
+    }
+  }
+  /**
+   * Escalate an internal SDK diagnostic to the telemetry stream (self-instrumentation). This is the
+   * sink behind {@link Logger.reportTelemetry}; chosen internal failure sites route here so faults
+   * that are otherwise only visible with `debug: true` become observable in the field.
+   *
+   * @remarks
+   * Bounded and deduped per load (a persistent fault — blocked storage, a downed endpoint — cannot
+   * flood the stream), re-entrancy-guarded so it can never recurse, and it never throws into the
+   * host. Diagnostics raised before the queue exists (early boot) are buffered and replayed once the
+   * queue is ready. Messages must be stable and low-cardinality (no raw error objects / PII).
+   */
+  reportTelemetry(level, message) {
+    if (this.telemetryReporting) {
+      return;
+    }
+    this.telemetryReporting = true;
+    try {
+      if (this.reportedTelemetryKeys.has(message) || this.reportedTelemetryKeys.size >= MAX_SELF_TELEMETRY) {
+        return;
+      }
+      this.reportedTelemetryKeys.add(message);
+      if (!this.telemetryReady) {
+        this.pendingSelfTelemetry.push({ level, message });
+        return;
+      }
+      this.telemetry(level, message);
+    } catch {
+    } finally {
+      this.telemetryReporting = false;
+    }
+  }
+  /**
+   * Synchronously flush any pending events and low events via beacon. Use during page-unload
+   * style teardown where async flushing is unreliable.
+   *
+   * @param reason What triggered the flush; recorded as `meta.flushReason` on the batch. Defaults
+   * to a direct call by the host app.
+   *
+   * @internal
+   */
+  flushKeepalive(reason = "manual") {
+    try {
+      this.queue.flushKeepalive(reason);
+    } catch (error) {
+      this.logger.error("Failed to flush queue keepalive", error);
+    }
+  }
+  /**
+   * Keepalive flush requested by a low-event tracker's `pagehide` teardown. Gated by the
+   * server-controlled trigger switch `tlf` (boot-snapshot, default true = historical behavior):
+   * disabling it server-side makes low-event delivery rely solely on the queue's own triggers.
+   *
+   * @internal
+   */
+  lowEventFlushKeepalive() {
+    if (!this.config.tlf) {
+      return;
+    }
+    this.flushKeepalive("low-event-teardown");
+  }
+  /**
+   * Flush any pending events and release all resources (timers, event listeners).
+   *
+   * @remarks
+   * After calling destroy, the tracker must not be used. Operation objects
+   * returned by factory methods (e.g. `passwordLoginFullOperation`) that hold
+   * DOM references must be destroyed separately by the caller.
+   * The final flush is gated by the server-controlled trigger switch `td` (default true);
+   * resources are released either way.
+   */
+  async destroy() {
+    this.bridge?.stop();
+    this.configManager?.destroy();
+    this.passwordManagerSampler?.destroy();
+    this.windowObserver?.destroy();
+    this.deviceInfoManager.destroy();
+    if (this.config.td) {
+      try {
+        await this.queue.flush("destroy");
+      } catch (error) {
+        this.logger.error("Failed to flush queue during destroy", error);
+      }
+    }
+    this.queue.destroy();
+  }
+  // Session Management
+  /**
+   * Return the Observe session id this tracker is currently reporting under.
+   *
+   * @remarks
+   * Use this to route a server-side event into the same session the browser reports to: read the id,
+   * pass it to your own backend, and let the backend use it as the `sessionID` of its ingest call.
+   * Reading it here is the supported path — the storage layout behind it is an implementation detail
+   * that has already changed once (per-tab `sessionStorage` to the cross-tab continuity record).
+   *
+   * The value is **not stable for the lifetime of the page**. It changes on
+   * {@link CorbadoTracker.resetSession}, when this tab adopts a continuity session another tab
+   * rotated to, and when a failed bootstrap recovers. Read it at the moment you need it; never cache
+   * it across a request.
+   *
+   * `undefined` means no session id could be established at all — an environment without Web Crypto,
+   * where tracking is not working either. Skip the server-side event instead of sending an empty id:
+   * the ingest API requires a UUID and would reject the batch.
+   *
+   * @returns The current session id, or `undefined` if none could be established.
+   *
+   * @example
+   * ```typescript
+   * const sessionId = tracker.getSessionId();
+   * if (sessionId) {
+   *   await fetch("/api/checkout", {
+   *     method: "POST",
+   *     body: JSON.stringify({ ...payload, observeSessionId: sessionId }),
+   *   });
+   * }
+   * ```
+   */
+  getSessionId() {
+    if (!this.sessionId) {
+      const recovered = this.resolveSession();
+      if (recovered) {
+        this.sessionId = recovered;
+        this.queue.setSessionId(recovered);
+      }
+    }
+    return this.sessionId || void 0;
+  }
+};
+export {
+  CorbadoTrackerCore
+};