@corbado/observe 1.7.1 → 1.8.0

package/dist/analysis/config-manager.mjs

@@ -0,0 +1,83 @@
+// src/config-manager.ts
+import { cacheConfig, loadCachedConfig, parseReliabilityConfig } from "./config.mjs";
+var CONFIG_FETCH_TIMEOUT_MS = 10 * 1e3;
+var CONFIG_REFRESH_INTERVAL_MS = 10 * 60 * 1e3;
+var CONFIG_RETRY_DELAYS_MS = [1e3, 3e3];
+var ConfigManager = class {
+  constructor(url, storage, logger) {
+    this.url = url;
+    this.storage = storage;
+    this.logger = logger;
+    this.initialConfig = loadCachedConfig(storage) ?? void 0;
+  }
+  initialConfig;
+  refreshTimer;
+  requestTimer;
+  retryTimer;
+  controller;
+  fetching = false;
+  stopped = false;
+  onConfig;
+  start(onConfig) {
+    if (this.stopped || this.onConfig) return;
+    this.onConfig = onConfig;
+    void this.fetchConfig();
+  }
+  async fetchConfig(attempt = 0) {
+    if (this.stopped || this.fetching) return;
+    if (attempt === 0) {
+      clearTimeout(this.refreshTimer);
+      clearTimeout(this.retryTimer);
+      this.refreshTimer = setTimeout(() => void this.fetchConfig(), CONFIG_REFRESH_INTERVAL_MS);
+    }
+    this.fetching = true;
+    const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+    this.controller = controller;
+    this.requestTimer = controller ? setTimeout(() => controller.abort(), CONFIG_FETCH_TIMEOUT_MS) : void 0;
+    let retryable = true;
+    try {
+      const response = await fetch(this.url, {
+        method: "GET",
+        cache: "no-store",
+        ...controller ? { signal: controller.signal } : {}
+      });
+      if (!response.ok) {
+        retryable = (response.status === 408 || response.status === 429 || response.status >= 500) && !response.headers.has("Retry-After");
+        throw new Error(`SDK config request failed (${response.status})`);
+      }
+      const raw = await response.json();
+      retryable = false;
+      const config = parseReliabilityConfig(raw);
+      if (!config) throw new Error("Invalid SDK config response");
+      if (this.stopped || controller?.signal.aborted) return;
+      cacheConfig(this.storage, config);
+      this.onConfig?.(config);
+    } catch (error) {
+      if (!this.stopped) {
+        this.logger.error("Failed to fetch SDK config", error);
+        const delay = CONFIG_RETRY_DELAYS_MS[attempt];
+        if ((retryable && !(error instanceof SyntaxError) || controller?.signal.aborted) && delay !== void 0) {
+          this.retryTimer = setTimeout(() => void this.fetchConfig(attempt + 1), delay);
+        }
+      }
+    } finally {
+      clearTimeout(this.requestTimer);
+      this.requestTimer = void 0;
+      this.controller = void 0;
+      this.fetching = false;
+    }
+  }
+  destroy() {
+    this.stopped = true;
+    clearTimeout(this.refreshTimer);
+    clearTimeout(this.requestTimer);
+    clearTimeout(this.retryTimer);
+    this.controller?.abort();
+    this.onConfig = void 0;
+  }
+};
+export {
+  CONFIG_FETCH_TIMEOUT_MS,
+  CONFIG_REFRESH_INTERVAL_MS,
+  ConfigManager
+};

package/dist/analysis/config.mjs

@@ -0,0 +1,216 @@
+// src/config.ts
+var CONFIG_STORAGE_KEY = "cbo_sdk_config";
+var CONFIG_REQUEST_HEADER = "X-Corbado-Observe-Config";
+var DEFAULT_FLUSH_INTERVAL_MS = 500;
+var DEFAULT_SEQ_LOCK_TIMEOUT_MS = 50;
+var DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS = 1e3;
+var CONFIG_BOUNDS = {
+  flushIntervalMs: { min: 100, max: 6e4 },
+  retryMaxAttempts: { min: 1, max: 10 },
+  retryDelayMs: { min: 50, max: 12e4 },
+  sessionInactivityMs: { min: 6e4, max: 864e5 },
+  // 0 is the sentinel that disables the seq Web Lock, so it must survive clamping.
+  seqLockTimeoutMs: { min: 0, max: 250 },
+  // Below ~10ms even a working browser API would time out on every load; above 10s the device info
+  // snapshot would arrive so late that early events ship without it anyway.
+  deviceInfoCollectorTimeoutMs: { min: 10, max: 1e4 },
+  // A long list of priority flow types would degrade toward flush-per-enqueue; cap it.
+  flushOnFlowTypeFinished: { maxEntries: 20, maxNameLength: 100 },
+  // Query keys whose values stay in reported page URLs; the server caps identically.
+  sourcePathQueryAllow: { maxEntries: 50, maxKeyLength: 64 }
+};
+var DEFAULT_SESSION_INACTIVITY_MS = 30 * 60 * 1e3;
+var DEFAULT_RELIABILITY_CONFIG = {
+  version: "",
+  flushIntervalMs: DEFAULT_FLUSH_INTERVAL_MS,
+  durableOutbox: false,
+  durableLowOutbox: false,
+  beaconKeepalive: false,
+  sessionContinuity: false,
+  sessionInactivityMs: DEFAULT_SESSION_INACTIVITY_MS,
+  seqLockTimeoutMs: DEFAULT_SEQ_LOCK_TIMEOUT_MS,
+  // Flush-trigger switches are ON by default: they gate existing delivery behavior, so the safe
+  // fallback is "keep flushing" (the opposite polarity of the feature flags above).
+  tvc: true,
+  tph: true,
+  td: true,
+  tlf: true,
+  // Telemetry defaults ON (on out of the box, per product decision); flush-on-telemetry defaults OFF
+  // so a telemetry entry alone never triggers a flush — it piggybacks the next event request.
+  telemetry: true,
+  flushOnTelemetry: false,
+  flushOnFlowTypeFinished: [],
+  deviceInfoCollectorTimeoutMs: DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS,
+  // Diagnostic stream, off until switched on server-side for an investigation.
+  deviceInfoTiming: false,
+  rawErrors: true,
+  // Password manager detection defaults ON; a project can switch it off server-side.
+  pmd: true,
+  retry: {
+    maxAttempts: 1,
+    baseDelayMs: 0,
+    maxDelayMs: 0
+  },
+  aap: "",
+  // Query values in reported page URLs are masked unless their key is allowlisted (none by default)
+  // or the project opts out with "all": URLs regularly carry tokens and credentials.
+  sourcePathQuery: "allowlist",
+  sourcePathQueryAllow: []
+};
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function asNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function asBoolean(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+function asString(value, fallback) {
+  return typeof value === "string" ? value : fallback;
+}
+function asFlowTypeList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(
+    (name) => typeof name === "string" && name.length > 0 && name.length <= CONFIG_BOUNDS.flushOnFlowTypeFinished.maxNameLength
+  ).slice(0, CONFIG_BOUNDS.flushOnFlowTypeFinished.maxEntries);
+}
+function asSourcePathQuery(value) {
+  return typeof value === "string" && value.trim().toLowerCase() === "all" ? "all" : "allowlist";
+}
+function asQueryKeyList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((key) => typeof key === "string").map((key) => key.trim()).filter((key) => key.length > 0 && key.length <= CONFIG_BOUNDS.sourcePathQueryAllow.maxKeyLength).slice(0, CONFIG_BOUNDS.sourcePathQueryAllow.maxEntries);
+}
+function parseReliabilityConfig(raw) {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const value = raw;
+  if (typeof value.version !== "string" || value.version === "") {
+    return null;
+  }
+  return normalizeReliabilityConfig(value);
+}
+function normalizeReliabilityConfig(value) {
+  const retryRaw = value.retry && typeof value.retry === "object" ? value.retry : {};
+  const baseDelayMs = clamp(
+    asNumber(retryRaw.baseDelayMs, DEFAULT_RELIABILITY_CONFIG.retry.baseDelayMs),
+    CONFIG_BOUNDS.retryDelayMs.min,
+    CONFIG_BOUNDS.retryDelayMs.max
+  );
+  return {
+    version: asString(value.version, ""),
+    flushIntervalMs: clamp(
+      asNumber(value.flushIntervalMs, DEFAULT_RELIABILITY_CONFIG.flushIntervalMs),
+      CONFIG_BOUNDS.flushIntervalMs.min,
+      CONFIG_BOUNDS.flushIntervalMs.max
+    ),
+    durableOutbox: value.durableOutbox === true,
+    durableLowOutbox: value.durableLowOutbox === true,
+    beaconKeepalive: value.beaconKeepalive === true,
+    sessionContinuity: value.sessionContinuity === true,
+    sessionInactivityMs: clamp(
+      asNumber(value.sessionInactivityMs, DEFAULT_RELIABILITY_CONFIG.sessionInactivityMs),
+      CONFIG_BOUNDS.sessionInactivityMs.min,
+      CONFIG_BOUNDS.sessionInactivityMs.max
+    ),
+    seqLockTimeoutMs: clamp(
+      asNumber(value.seqLockTimeoutMs, DEFAULT_RELIABILITY_CONFIG.seqLockTimeoutMs),
+      CONFIG_BOUNDS.seqLockTimeoutMs.min,
+      CONFIG_BOUNDS.seqLockTimeoutMs.max
+    ),
+    tvc: asBoolean(value.tvc, DEFAULT_RELIABILITY_CONFIG.tvc),
+    tph: asBoolean(value.tph, DEFAULT_RELIABILITY_CONFIG.tph),
+    td: asBoolean(value.td, DEFAULT_RELIABILITY_CONFIG.td),
+    tlf: asBoolean(value.tlf, DEFAULT_RELIABILITY_CONFIG.tlf),
+    // Master switch defaults ON (like the trigger switches): a partial payload keeps telemetry on.
+    telemetry: asBoolean(value.telemetry, DEFAULT_RELIABILITY_CONFIG.telemetry),
+    // Feature switch defaults OFF: a partial payload can never silently enable immediate flushing.
+    flushOnTelemetry: value.flushOnTelemetry === true,
+    flushOnFlowTypeFinished: asFlowTypeList(value.flushOnFlowTypeFinished),
+    deviceInfoCollectorTimeoutMs: clamp(
+      asNumber(value.deviceInfoCollectorTimeoutMs, DEFAULT_RELIABILITY_CONFIG.deviceInfoCollectorTimeoutMs),
+      CONFIG_BOUNDS.deviceInfoCollectorTimeoutMs.min,
+      CONFIG_BOUNDS.deviceInfoCollectorTimeoutMs.max
+    ),
+    // Feature switch defaults OFF: a partial payload can never silently enable the timing stream.
+    deviceInfoTiming: value.deviceInfoTiming === true,
+    rawErrors: asBoolean(value.rawErrors, DEFAULT_RELIABILITY_CONFIG.rawErrors),
+    pmd: asBoolean(value.pmd, DEFAULT_RELIABILITY_CONFIG.pmd),
+    aap: asString(value.aap, ""),
+    sourcePathQuery: asSourcePathQuery(value.sourcePathQuery),
+    sourcePathQueryAllow: asQueryKeyList(value.sourcePathQueryAllow),
+    retry: {
+      maxAttempts: clamp(
+        asNumber(retryRaw.maxAttempts, DEFAULT_RELIABILITY_CONFIG.retry.maxAttempts),
+        CONFIG_BOUNDS.retryMaxAttempts.min,
+        CONFIG_BOUNDS.retryMaxAttempts.max
+      ),
+      baseDelayMs,
+      maxDelayMs: clamp(
+        asNumber(retryRaw.maxDelayMs, DEFAULT_RELIABILITY_CONFIG.retry.maxDelayMs),
+        baseDelayMs,
+        CONFIG_BOUNDS.retryDelayMs.max
+      )
+    }
+  };
+}
+function resolveReliabilityConfig(serverConfig, overrides = {}) {
+  const base = serverConfig ?? DEFAULT_RELIABILITY_CONFIG;
+  const fields = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== void 0));
+  const retryFields = Object.fromEntries(
+    Object.entries(overrides.retry ?? {}).filter(([, value]) => value !== void 0)
+  );
+  const resolved = normalizeReliabilityConfig({ ...base, ...fields, retry: { ...base.retry, ...retryFields } });
+  resolved.retry = {
+    ...base.retry,
+    ...Object.fromEntries(
+      Object.keys(retryFields).map((key) => [key, resolved.retry[key]])
+    )
+  };
+  resolved.retry.maxDelayMs = Math.max(resolved.retry.baseDelayMs, resolved.retry.maxDelayMs);
+  return resolved;
+}
+function resolveFixedDataConfig(raw) {
+  try {
+    if (!raw || typeof raw !== "object") {
+      return void 0;
+    }
+    const value = raw;
+    const pmd = value.pmd;
+    const pmdExplicit = typeof pmd === "boolean";
+    return {
+      pmd: pmdExplicit ? pmd : false,
+      pmdExplicit,
+      privateMode: asBoolean(value.privateMode, true)
+    };
+  } catch {
+    return void 0;
+  }
+}
+function loadCachedConfig(storage) {
+  return parseReliabilityConfig(storage.getItem(CONFIG_STORAGE_KEY));
+}
+function cacheConfig(storage, config) {
+  storage.setItem(CONFIG_STORAGE_KEY, config);
+}
+export {
+  CONFIG_BOUNDS,
+  CONFIG_REQUEST_HEADER,
+  CONFIG_STORAGE_KEY,
+  DEFAULT_DEVICE_INFO_COLLECTOR_TIMEOUT_MS,
+  DEFAULT_FLUSH_INTERVAL_MS,
+  DEFAULT_RELIABILITY_CONFIG,
+  DEFAULT_SEQ_LOCK_TIMEOUT_MS,
+  DEFAULT_SESSION_INACTIVITY_MS,
+  cacheConfig,
+  loadCachedConfig,
+  parseReliabilityConfig,
+  resolveFixedDataConfig,
+  resolveReliabilityConfig
+};

package/dist/analysis/device-info-manager.mjs

@@ -0,0 +1,153 @@
+// src/device-info-manager.ts
+function isDocumentHidden() {
+  return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+var DeviceInfoManager = class {
+  constructor(logger, source, refreshInterval, attachInterval, diagnostics, onUndelivered) {
+    this.logger = logger;
+    this.source = source;
+    this.refreshInterval = refreshInterval;
+    this.attachInterval = attachInterval;
+    this.diagnostics = diagnostics;
+    this.onUndelivered = onUndelivered;
+  }
+  snapshot;
+  snapshotPhase;
+  publishedAt = 0;
+  version = 0;
+  deliveredVersion = 0;
+  refreshedAt = 0;
+  lastAttachedAt = null;
+  /** True once any event of this page asked for device info: unload reports only matter then. */
+  eventsSeen = false;
+  refreshPromise;
+  timer;
+  destroyed = false;
+  start() {
+    void this.refresh();
+  }
+  /**
+   * Device info to attach to an event being tracked now: the current snapshot when its version was
+   * not delivered yet, otherwise at most once per attach interval.
+   */
+  getForEvent() {
+    this.eventsSeen = true;
+    if (Date.now() - this.refreshedAt >= this.refreshInterval) {
+      void this.refresh();
+    }
+    if (!this.snapshot) {
+      return void 0;
+    }
+    if (this.version !== this.deliveredVersion) {
+      return this.markDelivered("event");
+    }
+    if (this.lastAttachedAt !== null && Date.now() - this.lastAttachedAt < this.attachInterval) {
+      return void 0;
+    }
+    this.lastAttachedAt = Date.now();
+    return this.snapshot;
+  }
+  /** True when a snapshot version exists that no event has carried yet. */
+  hasUndelivered() {
+    return this.snapshot !== void 0 && this.version !== this.deliveredVersion;
+  }
+  /**
+   * The undelivered snapshot, marked as delivered, for the queue to attach to an event of this page in
+   * the batch it is about to send; undefined when everything was delivered already.
+   */
+  takeUndelivered() {
+    if (!this.hasUndelivered()) {
+      return void 0;
+    }
+    return this.markDelivered("flush");
+  }
+  /** True when an undelivered snapshot may be sent on its own: this page tracked events. */
+  hasStandalone() {
+    return this.eventsSeen && this.hasUndelivered();
+  }
+  /** The undelivered snapshot, marked as delivered, for the request-level device info of a batch. */
+  takeStandalone() {
+    if (!this.hasStandalone()) {
+      return void 0;
+    }
+    return this.markDelivered("request");
+  }
+  destroy() {
+    this.destroyed = true;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+  }
+  markDelivered(path) {
+    this.deliveredVersion = this.version;
+    this.lastAttachedAt = Date.now();
+    if (this.snapshotPhase === "update") {
+      this.report(`device info update delivered via ${path} after ${Math.max(0, Date.now() - this.publishedAt)}ms`);
+    }
+    return this.snapshot;
+  }
+  publish(info, phase) {
+    if (phase === "fast") {
+      this.refreshedAt = Date.now();
+    }
+    if (this.snapshot && JSON.stringify(this.snapshot) === JSON.stringify(info)) {
+      return;
+    }
+    this.snapshot = info;
+    this.snapshotPhase = phase;
+    this.publishedAt = Date.now();
+    this.version++;
+    if (this.eventsSeen && this.onUndelivered) {
+      try {
+        this.onUndelivered();
+      } catch (error) {
+        this.logger.error("Failed to announce undelivered device info", error);
+      }
+    }
+  }
+  report(message) {
+    if (!this.diagnostics) {
+      return;
+    }
+    try {
+      if (this.diagnostics.timing()) {
+        this.diagnostics.emit("info", message);
+      }
+    } catch (error) {
+      this.logger.error("Failed to report device info delivery", error);
+    }
+  }
+  scheduleRefresh() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+    }
+    this.timer = setTimeout(() => void this.refresh(), this.refreshInterval);
+  }
+  refresh() {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+    if (this.snapshot && isDocumentHidden()) {
+      if (!this.destroyed) {
+        this.scheduleRefresh();
+      }
+      return Promise.resolve();
+    }
+    const refresh = this.snapshot !== void 0;
+    this.refreshPromise = Promise.resolve().then(() => this.source.collect((info, phase) => this.publish(info, phase), { refresh })).catch((error) => this.logger.error("Failed to refresh device info", error)).finally(() => {
+      this.refreshPromise = void 0;
+      if (!this.destroyed) {
+        this.scheduleRefresh();
+      }
+    });
+    return this.refreshPromise;
+  }
+};
+export {
+  DeviceInfoManager
+};