@corbado/observe 1.7.2 → 1.8.0

package/dist/analysis/queue.mjs

@@ -0,0 +1,887 @@
+// src/queue.ts
+import { v7 as uuidv7 } from "uuid";
+import { AuthEventName } from "./types.mjs";
+import { CONFIG_REQUEST_HEADER, DEFAULT_RELIABILITY_CONFIG } from "./config.mjs";
+import { EventStore } from "./store/event-store.mjs";
+var PROBE_QUEUE_MAX_ITEMS = 500;
+var PROBE_QUEUE_MAX_BYTES = 512 * 1024;
+var PROBE_BATCH_MAX_ITEMS = 200;
+var PROBE_BATCH_MAX_BYTES = 200 * 1024;
+var PROBE_PAYLOAD_MAX_BYTES = 16 * 1024;
+var UNLOAD_BUDGET_BYTES = 6e4;
+var UNLOAD_PROBE_MAX_BYTES = 32e3;
+function utf8Length(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319 && i + 1 < text.length) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+var RequestQueue = class {
+  constructor(logger, transport, sessionId, sdk, options = {}, storage) {
+    this.logger = logger;
+    this.transport = transport;
+    this.sessionId = sessionId;
+    this.sdk = sdk;
+    this.storage = storage;
+    this.batchSize = options.batchSize || 50;
+    this.flushIntervalOverride = options.flushInterval;
+    this.debug = options.debug ?? false;
+    this.requestConfig = options.requestConfig ?? true;
+    this.onConfigReceived = options.onConfigReceived;
+    this.getDataPolicy = options.getDataPolicy;
+    this.fixedData = options.fixedData === true;
+    this.beforeEventBatchSend = options.beforeEventBatchSend;
+    this.standaloneDeviceInfo = options.standaloneDeviceInfo;
+    this.config = options.config ?? DEFAULT_RELIABILITY_CONFIG;
+    this.priorityFlowTypes = new Set(this.config.flushOnFlowTypeFinished);
+    this.outboxLockName = options.outboxLockName;
+    if (this.config.durableOutbox && this.storage) {
+      this.store = new EventStore(this.storage, this.logger, void 0, void 0, this.outboxLockName);
+      this.pending = this.store.all();
+    }
+    if (this.storage) {
+      this.lowStore = new EventStore(
+        this.storage,
+        this.logger,
+        1e3,
+        256 * 1024,
+        `${this.outboxLockName ?? "cbo_outbox"}:lows`,
+        "cbo_low_outbox_v1"
+      );
+      const recovered = this.lowStore.all();
+      this.lowPending = recovered.filter((entry) => this.validPendingLow(entry));
+      void this.lowStore.remove(recovered.filter((entry) => !this.validPendingLow(entry)).map((entry) => entry.id));
+    }
+    this.setupLifecycleHooks();
+    if (this.pending.length > 0 || this.lowPending.length > 0) {
+      this.dirtySinceSyncFlush = true;
+      this.scheduleFlush(0, "recovery");
+    }
+  }
+  pending = [];
+  lowsQueue = [];
+  lowPending = [];
+  lowStore;
+  /**
+   * Diagnostic telemetry buffered for the current session. Best-effort and never persisted. Attached to the next outgoing batch for this session; a telemetry entry alone never arms
+   * the flush timer (it piggybacks), unless `config.flushOnTelemetry` escalates to an immediate flush.
+   */
+  telemetryQueue = [];
+  /**
+   * Probe items (`tracker.probe()`): in memory only — never the durable outbox — capped by
+   * {@link PROBE_QUEUE_MAX_ITEMS} / {@link PROBE_QUEUE_MAX_BYTES}. They arm the flush timer, ride
+   * the regular batches (probe-only batches allowed), retry under `config.retry`, and are the lowest
+   * priority at unload (a separate request after the event request, within the remaining budget).
+   */
+  probeQueue = [];
+  probeBytes = 0;
+  /** Probe items dropped on this load (caps, permanent rejection, exhausted retries, unload budget). */
+  probesDropped = 0;
+  timer = null;
+  isFlushing = false;
+  flushingDone;
+  destroyed = false;
+  /**
+   * True when something was enqueued (or recovered) since the last sync flush. visibilitychange,
+   * pagehide and per-input flushKeepalive calls all funnel into flushSync; this flag makes the
+   * duplicate calls no-ops. The async flush path ignores it.
+   */
+  dirtySinceSyncFlush = false;
+  onVisibilityChange = null;
+  onPageHide = null;
+  batchSize;
+  flushIntervalOverride;
+  debug;
+  requestConfig;
+  onConfigReceived;
+  getDataPolicy;
+  fixedData;
+  beforeEventBatchSend;
+  standaloneDeviceInfo;
+  /** Current delivery policy, including live updates. */
+  config;
+  /**
+   * Flow types whose completion triggers an immediate flush at enqueue time
+   * (config.flushOnFlowTypeFinished).
+   */
+  priorityFlowTypes;
+  /** Scoped Web Lock name for the durable outbox; undefined = EventStore's shared default. */
+  outboxLockName;
+  store;
+  /**
+   * Once the server has answered the config request with a 2xx (200 = fresh config cached for the
+   * next load, 204 = cached version still current) we stop sending the header for this load. A
+   * transport-level failure or error status keeps the request pending for the next flush.
+   */
+  configResolved = false;
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+  flushInterval() {
+    return this.flushIntervalOverride ?? this.config.flushIntervalMs;
+  }
+  /**
+   * Error situations:
+   *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue event"
+   */
+  enqueue(event, capturedSessionId = this.sessionId) {
+    try {
+      const entry = {
+        id: event.id,
+        sessionId: capturedSessionId,
+        flushAfter: 0,
+        attempts: 0,
+        event
+      };
+      this.pending.push(entry);
+      void this.store?.add(entry);
+      this.scheduleAfterEnqueue(event);
+    } catch (error) {
+      this.logger.error("Failed to enqueue event", error);
+    }
+  }
+  /**
+   * Error situations:
+   *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue low event"
+   */
+  enqueueLow(low, capturedSessionId = this.sessionId) {
+    try {
+      const event = { ...low, id: low.id ?? uuidv7() };
+      if (this.config.durableLowOutbox) {
+        const entry = {
+          id: event.id,
+          sessionId: capturedSessionId,
+          event,
+          attempts: 0,
+          flushAfter: 0
+        };
+        this.lowPending.push(entry);
+        this.lowPending = this.lowPending.slice(-1e3);
+        void this.lowStore?.add(entry);
+      } else {
+        this.lowsQueue.push({ sessionId: capturedSessionId, event });
+      }
+      this.scheduleAfterEnqueue();
+    } catch (error) {
+      this.logger.error("Failed to enqueue low event", error);
+    }
+  }
+  /**
+   * A device info snapshot that no event carried is waiting ({@link QueueOptions.standaloneDeviceInfo}): arm the
+   * ordinary flush timer so it goes out even when no event follows, and let the next unload flush pick it up.
+   * An event tracked before the timer fires carries it instead.
+   *
+   * Error situations:
+   *  - Any error while scheduling the flush: log "Failed to schedule device info flush"
+   */
+  notifyDeviceInfo() {
+    try {
+      this.dirtySinceSyncFlush = true;
+      this.scheduleFlush(this.flushInterval(), "timer");
+    } catch (error) {
+      this.logger.error("Failed to schedule device info flush", error);
+    }
+  }
+  /**
+   * Buffer a diagnostic telemetry entry for delivery with the next event batch.
+   *
+   * @remarks
+   * The switch `config.telemetry` gates collection. Entries buffered while on remain eligible for delivery.
+   * By default a telemetry entry does NOT arm the flush timer — it piggybacks the next flush caused
+   * by events or a lifecycle signal (it is marked dirty so the unload flush picks it up). When
+   * `config.flushOnTelemetry` is on it escalates to an immediate flush.
+   *
+   * Error situations:
+   *  - Any error while enqueueing or triggering the flush: log "Failed to enqueue telemetry"
+   */
+  enqueueTelemetry(entry) {
+    try {
+      if (!this.config.telemetry) {
+        return;
+      }
+      this.telemetryQueue.push(entry);
+      this.dirtySinceSyncFlush = true;
+      if (this.config.flushOnTelemetry) {
+        void this.flush("telemetry");
+      }
+    } catch (error) {
+      this.logger.error("Failed to enqueue telemetry", error);
+    }
+  }
+  /**
+   * Queue a probe item (in memory only). The payload is snapshotted (serialized once) so later host
+   * mutations cannot change it; items over {@link PROBE_PAYLOAD_MAX_BYTES} are dropped, and the
+   * oldest items are dropped beyond the queue caps. Arms the normal flush timer.
+   *
+   * Error situations:
+   *  - Any error while enqueueing or scheduling the flush timer: log "Failed to enqueue probe"
+   */
+  enqueueProbe(entry, capturedSessionId = this.sessionId) {
+    try {
+      if (this.destroyed) return;
+      const payloadJson = JSON.stringify(entry.payload);
+      if (typeof payloadJson !== "string" || utf8Length(payloadJson) > PROBE_PAYLOAD_MAX_BYTES) {
+        this.probesDropped++;
+        return;
+      }
+      const snapshot = { ...entry, payload: JSON.parse(payloadJson) };
+      const bytes = utf8Length(JSON.stringify(snapshot));
+      this.probeQueue.push({ sessionId: capturedSessionId, entry: snapshot, bytes, attempts: 0, flushAfter: 0 });
+      this.probeBytes += bytes;
+      while (this.probeQueue.length > PROBE_QUEUE_MAX_ITEMS || this.probeBytes > PROBE_QUEUE_MAX_BYTES && this.probeQueue.length > 1) {
+        const dropped = this.probeQueue.shift();
+        this.probeBytes -= dropped.bytes;
+        this.probesDropped++;
+      }
+      this.scheduleFlush(this.flushInterval(), "timer");
+    } catch (error) {
+      this.logger.error("Failed to enqueue probe", error);
+    }
+  }
+  /** Number of probe items dropped on this load (diagnostics / tests). */
+  droppedProbeCount() {
+    return this.probesDropped;
+  }
+  dueProbes(now) {
+    return this.probeQueue.filter((item) => item.flushAfter <= now);
+  }
+  /** Oldest-first selection for one session, within an item and byte cap (at least one item when any fits the item cap). */
+  selectProbes(candidates, sessionId, maxItems, maxBytes) {
+    const selected = [];
+    let bytes = 0;
+    for (const item of candidates) {
+      if (selected.length >= maxItems) break;
+      if (item.sessionId !== sessionId) continue;
+      if (bytes + item.bytes > maxBytes) {
+        if (selected.length === 0 && maxBytes >= PROBE_BATCH_MAX_BYTES) selected.push(item);
+        break;
+      }
+      bytes += item.bytes;
+      selected.push(item);
+    }
+    return selected;
+  }
+  removeProbes(items) {
+    if (items.length === 0) return;
+    const removed = new Set(items);
+    this.probeQueue = this.probeQueue.filter((item) => !removed.has(item));
+    for (const item of items) this.probeBytes -= item.bytes;
+  }
+  dropProbes(items) {
+    this.removeProbes(items);
+    this.probesDropped += items.length;
+  }
+  /** Same policy as events: 2xx delivered, non-retryable dropped, retryable backed off up to `config.retry.maxAttempts`. */
+  handleProbeSendResult(response, items, now) {
+    if (items.length === 0) return;
+    const status = response.statusCode;
+    if (typeof status === "number" && status >= 200 && status < 300) {
+      this.removeProbes(items);
+      return;
+    }
+    if (!this.isRetryable(status)) {
+      this.dropProbes(items);
+      return;
+    }
+    const maxAttempts = Math.max(1, this.config.retry.maxAttempts);
+    const retryAfterMs = this.parseRetryAfter(response);
+    const exhausted = [];
+    for (const item of items) {
+      item.attempts += 1;
+      if (item.attempts >= maxAttempts) exhausted.push(item);
+      else item.flushAfter = now + this.backoffForAttempt(item.attempts, retryAfterMs);
+    }
+    this.dropProbes(exhausted);
+  }
+  /**
+   * Unload / final teardown: one probe-only request for the current session within `budget` bytes,
+   * sent after the event request so the events' delivery is unaffected. Leftovers are dropped when
+   * `dropRest` (pagehide, destroy); otherwise they stay queued.
+   */
+  sendUnloadProbes(budget, reason, dropRest, useBeacon) {
+    const sessionId = this.sessionId;
+    const envelope = { sessionId, events: [], sdk: this.sdk, probes: [] };
+    this.attachBatchMeta(envelope, [], reason);
+    const overhead = utf8Length(JSON.stringify(envelope)) + 120;
+    const items = budget > overhead ? this.selectProbes(this.probeQueue, sessionId, PROBE_BATCH_MAX_ITEMS, budget - overhead) : [];
+    if (items.length > 0) {
+      envelope.probes = items.map((item) => item.entry);
+      this.attachBatchMeta(envelope, items, reason);
+      if (useBeacon && this.config.beaconKeepalive && this.transport.sendBeacon) {
+        this.transport.sendBeacon(envelope);
+      } else {
+        void Promise.resolve(this.transport.send(envelope)).catch(() => void 0);
+      }
+      this.removeProbes(items);
+    }
+    if (dropRest) this.dropProbes(this.probeQueue.slice());
+  }
+  scheduleAfterEnqueue(event) {
+    this.dirtySinceSyncFlush = true;
+    if (event !== void 0 && this.isPriorityEvent(event)) {
+      void this.flush("flow-finished");
+      return;
+    }
+    this.scheduleFlush(this.flushInterval(), "timer");
+  }
+  /**
+   * Whether this event completes one of the configured priority flow types. Only the two flow
+   * completion events qualify — `flow_finished` and `flow_auto_finished`, both carrying the
+   * finished flow in `data.flowName`. Custom events never match, even when named like one of them.
+   */
+  isPriorityEvent(event) {
+    if (event.type !== "predefined") {
+      return false;
+    }
+    if (event.name !== AuthEventName.FlowFinished && event.name !== AuthEventName.FlowAutoFinished) {
+      return false;
+    }
+    const flowName = event.data?.flowName;
+    return typeof flowName === "string" && this.priorityFlowTypes.has(flowName);
+  }
+  /**
+   * Arm the flush timer. The `reason` travels with the timer into the flush it triggers; an
+   * already-armed timer keeps the reason it was armed with (the flush it fires is that flush, and
+   * it takes whatever accumulated in the meantime with it).
+   */
+  scheduleFlush(delay, reason) {
+    if (this.destroyed) {
+      return;
+    }
+    if (this.timer) {
+      return;
+    }
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush(reason);
+    }, delay);
+  }
+  clearTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+  /**
+   * @param reason What triggered this flush; stamped onto every batch it sends as
+   * `meta.flushReason`. Defaults to the ordinary interval cadence.
+   *
+   * Error situations:
+   *  - Queue is empty: return without calling transport.send
+   *  - A flush is already in progress: return without calling transport.send again
+   *  - transport.send rejects or throws, or any other error in the try block: log "Unexpected error in queue flush"
+   */
+  async flush(reason = "timer") {
+    if (this.destroyed) return;
+    if (this.isFlushing) {
+      if (reason === "destroy") {
+        await this.flushingDone;
+        try {
+          this.sendUnloadProbes(UNLOAD_PROBE_MAX_BYTES, reason, true, false);
+        } catch (error) {
+          this.logger.error("Unexpected error in queue flush", error);
+        }
+      }
+      return;
+    }
+    this.isFlushing = true;
+    let finish;
+    this.flushingDone = new Promise((resolve) => {
+      finish = resolve;
+    });
+    try {
+      this.clearTimer();
+      for (; ; ) {
+        const now = Date.now();
+        const due = this.getDuePending(now);
+        const dueLows = this.lowPending.filter((entry) => entry.flushAfter <= now);
+        const dueProbes = reason === "destroy" ? [] : this.dueProbes(now);
+        const onlyDeviceInfo = due.length === 0 && dueLows.length === 0 && this.lowsQueue.length === 0 && this.telemetryQueue.length === 0 && dueProbes.length === 0;
+        if (onlyDeviceInfo && !this.hasStandaloneDeviceInfo()) {
+          break;
+        }
+        const sessionId = due[0]?.sessionId ?? dueLows[0]?.sessionId ?? this.lowsQueue[0]?.sessionId ?? dueProbes[0]?.sessionId ?? this.sessionId;
+        const batchEntries = due.filter((entry) => entry.sessionId === sessionId).slice(0, this.batchSize);
+        const lowEntries = dueLows.filter((entry) => entry.sessionId === sessionId).slice(0, 100);
+        const lows = [...lowEntries.map((entry) => entry.event), ...this.takeLows(sessionId, 100 - lowEntries.length)];
+        this.prepareEvents(batchEntries, reason);
+        const telemetry = sessionId === this.sessionId ? this.takeTelemetry() : [];
+        const deviceInfo = sessionId === this.sessionId ? this.takeStandaloneDeviceInfo() : void 0;
+        const probeItems = this.selectProbes(dueProbes, sessionId, PROBE_BATCH_MAX_ITEMS, PROBE_BATCH_MAX_BYTES);
+        const batch = {
+          sessionId,
+          events: batchEntries.map((entry) => entry.event),
+          sdk: this.sdk
+        };
+        if (lows.length > 0) {
+          batch.lows = lows;
+        }
+        if (telemetry.length > 0) {
+          batch.telemetry = telemetry;
+        }
+        if (probeItems.length > 0) {
+          batch.probes = probeItems.map((item) => item.entry);
+        }
+        if (deviceInfo) {
+          batch.deviceInfo = deviceInfo;
+        }
+        if (onlyDeviceInfo && !deviceInfo) {
+          break;
+        }
+        this.attachBatchMeta(batch, [...batchEntries, ...lowEntries, ...probeItems], reason);
+        if (lowEntries.length) batch.deliveryAck = true;
+        const extraHeaders = this.shouldRequestConfig() ? { [CONFIG_REQUEST_HEADER]: this.config.version || "1" } : void 0;
+        let response = await this.transport.send(batch, extraHeaders).catch((error) => {
+          this.logger.error("Unexpected error in queue flush", error);
+          return {};
+        });
+        if (batch.deliveryAck && response.statusCode && response.statusCode >= 200 && response.statusCode < 300 && !response.deliveryAccepted) {
+          response = { ...response, statusCode: 503 };
+        }
+        if (this.requestConfig) this.handleConfigResponse(response);
+        this.handleLowSendResult(response, lowEntries, now);
+        this.handleProbeSendResult(response, probeItems, now);
+        if (!this.handleSendResult(response, batchEntries, now)) {
+          break;
+        }
+      }
+      if (reason === "destroy") {
+        this.sendUnloadProbes(UNLOAD_PROBE_MAX_BYTES, reason, true, false);
+      }
+    } catch (error) {
+      this.logger.error("Unexpected error in queue flush", error);
+    } finally {
+      this.isFlushing = false;
+      finish();
+      this.flushingDone = void 0;
+      this.rescheduleIfPending();
+    }
+  }
+  /**
+   * Stamps delivery metadata onto the batch: the trigger that caused this flush, the config version
+   * this load runs under (omitted on built-in defaults) and the number of prior failed delivery
+   * attempts (the max across its entries, only when at least one entry is a retry). `entry.attempts`
+   * is incremented on each failed flush, so it equals the retry count at send time. The data policy
+   * code (when one has ever been set) is read live, so it reflects the tracker state at send time.
+   * The transport later merges in `sent`/`transport`.
+   */
+  attachBatchMeta(batch, entries, reason) {
+    batch.meta = { ...batch.meta, flushReason: reason };
+    const dataPolicy = this.readDataPolicy();
+    if (dataPolicy !== void 0) {
+      batch.meta = { ...batch.meta, dataPolicy };
+    }
+    if (this.config.version) {
+      batch.meta = { ...batch.meta, configVersion: this.config.version };
+    }
+    if (this.fixedData) {
+      batch.meta = { ...batch.meta, fixedData: true };
+    }
+    const retryCount = entries.reduce((max, entry) => Math.max(max, entry.attempts), 0);
+    if (retryCount > 0) {
+      batch.meta = { ...batch.meta, retryCount };
+    }
+  }
+  /** Run the beforeEventBatchSend hook; a throwing hook must never break a flush. */
+  prepareEvents(entries, reason) {
+    if (!this.beforeEventBatchSend || entries.length === 0) {
+      return;
+    }
+    try {
+      this.beforeEventBatchSend(
+        entries.map((entry) => entry.event),
+        reason
+      );
+    } catch (error) {
+      this.logger.error("Failed to prepare events for sending", error);
+    }
+  }
+  /** The data policy code from the tracker, or undefined; a throwing getter must never break a flush. */
+  readDataPolicy() {
+    try {
+      return this.getDataPolicy?.();
+    } catch (error) {
+      this.logger.debug("Failed to read data policy for batch meta", error);
+      return void 0;
+    }
+  }
+  getDuePending(now) {
+    return this.pending.filter((entry) => entry.flushAfter <= now);
+  }
+  takeLows(sessionId = this.sessionId, limit = 100) {
+    const selected = this.lowsQueue.filter((entry) => entry.sessionId === sessionId).slice(0, limit);
+    const taken = new Set(selected);
+    this.lowsQueue = this.lowsQueue.filter((entry) => !taken.has(entry));
+    return selected.map((entry) => entry.event);
+  }
+  validPendingLow(entry) {
+    return typeof entry.event?.lowType === "string" && entry.event.id === entry.id && Number.isFinite(entry.event.ts) && entry.event.ts > Date.now() - 7 * 864e5;
+  }
+  removeLowEntries(ids) {
+    const removed = new Set(ids);
+    this.lowPending = this.lowPending.filter((entry) => !removed.has(entry.id));
+    void this.lowStore?.remove(ids);
+  }
+  handleLowSendResult(response, entries, now) {
+    const status = response.statusCode;
+    if (status !== void 0 && status >= 200 && status < 300) {
+      if (response.deliveryAccepted) this.removeLowEntries(entries.map((entry) => entry.id));
+      else this.deferLowEntries(entries, now);
+      return;
+    }
+    if (!this.isRetryable(status)) {
+      this.removeLowEntries(entries.map((entry) => entry.id));
+      this.logger.reportTelemetry?.("error", "low events rejected by ingestion");
+      return;
+    }
+    this.deferLowEntries(entries, now, this.parseRetryAfter(response));
+  }
+  deferLowEntries(entries, now, retryAfter = null) {
+    const expired = [];
+    for (const entry of entries) {
+      if (!this.validPendingLow(entry)) {
+        expired.push(entry.id);
+        continue;
+      }
+      entry.attempts = Math.min(entry.attempts + 1, 16);
+      entry.flushAfter = now + Math.max(
+        Math.min(6e4, 1e3 * 2 ** Math.min(entry.attempts, 6)),
+        this.backoffForAttempt(entry.attempts, retryAfter)
+      );
+    }
+    this.removeLowEntries(expired);
+    void this.lowStore?.update(entries.filter((entry) => !expired.includes(entry.id)));
+  }
+  hasStandaloneDeviceInfo() {
+    try {
+      return this.standaloneDeviceInfo?.has() ?? false;
+    } catch (error) {
+      this.logger.error("Failed to read device info for batch", error);
+      return false;
+    }
+  }
+  /** The snapshot for the request-level `deviceInfo`; a throwing source must never break a flush. */
+  takeStandaloneDeviceInfo() {
+    try {
+      return this.standaloneDeviceInfo?.take();
+    } catch (error) {
+      this.logger.error("Failed to read device info for batch", error);
+      return void 0;
+    }
+  }
+  takeTelemetry() {
+    const telemetry = this.telemetryQueue;
+    this.telemetryQueue = [];
+    return telemetry;
+  }
+  shouldRequestConfig() {
+    return this.requestConfig && !this.configResolved;
+  }
+  /**
+   * Handle the server's answer to the config request. With a cached boot config the boot-snapshot
+   * model applies: a fresh config is ONLY handed to `onConfigReceived` for caching and takes effect
+   * on the next load. A load that booted on the built-in defaults (nothing cached) has no prior
+   * behavior to stay coherent with — there the first server config is additionally applied live,
+   * so cold-storage visits (first visit, cleared storage) don't run their whole load without the
+   * reliability features.
+   */
+  handleConfigResponse(response) {
+    const status = response.statusCode;
+    if (typeof status === "number" && status >= 200 && status < 300) {
+      this.configResolved = true;
+    }
+    if (response.config) {
+      if (!this.config.version) {
+        this.updateConfig(response.config);
+      }
+      this.onConfigReceived?.(response.config);
+    }
+  }
+  /** Applies live delivery policy, retaining pending events, retry deadlines, and activated persistence. */
+  updateConfig(config) {
+    if (this.destroyed) return;
+    const intervalChanged = this.config.flushIntervalMs !== config.flushIntervalMs;
+    this.config = { ...config, durableOutbox: this.config.durableOutbox || config.durableOutbox };
+    this.priorityFlowTypes = new Set(config.flushOnFlowTypeFinished);
+    if (config.durableLowOutbox && this.lowsQueue.length) {
+      const queued = this.lowsQueue;
+      this.lowsQueue = [];
+      for (const { event, sessionId } of queued) this.enqueueLow(event, sessionId);
+    }
+    let recovered = false;
+    if (this.config.durableOutbox && this.storage && !this.store) {
+      this.store = new EventStore(this.storage, this.logger, void 0, void 0, this.outboxLockName);
+      const pendingIds = new Set(this.pending.map((entry) => entry.id));
+      const orphans = this.store.all().filter((entry) => !pendingIds.has(entry.id));
+      for (const entry of this.pending) void this.store.add(entry);
+      this.pending = [...orphans, ...this.pending];
+      recovered = orphans.length > 0;
+    }
+    if (recovered) {
+      this.dirtySinceSyncFlush = true;
+      this.clearTimer();
+      this.scheduleFlush(0, "recovery");
+    } else if (intervalChanged) {
+      this.clearTimer();
+      this.rescheduleIfPending();
+    }
+  }
+  handleSendResult(response, batchEntries, now) {
+    const status = response.statusCode;
+    const success = typeof status === "number" && status >= 200 && status < 300;
+    if (batchEntries.length === 0) {
+      return success;
+    }
+    if (success) {
+      this.removeEntries(batchEntries.map((entry) => entry.id));
+      return true;
+    }
+    if (!this.isRetryable(status)) {
+      this.removeEntries(batchEntries.map((entry) => entry.id));
+      return false;
+    }
+    const maxAttempts = Math.max(1, this.config.retry.maxAttempts);
+    const retryAfterMs = this.parseRetryAfter(response);
+    const exhausted = [];
+    const retried = [];
+    for (const entry of batchEntries) {
+      entry.attempts += 1;
+      if (entry.attempts >= maxAttempts) {
+        exhausted.push(entry.id);
+      } else {
+        entry.flushAfter = now + this.backoffForAttempt(entry.attempts, retryAfterMs);
+        retried.push(entry);
+      }
+    }
+    this.removeEntries(exhausted);
+    void this.store?.update(retried);
+    return false;
+  }
+  isRetryable(status) {
+    if (status === void 0) {
+      return true;
+    }
+    if (status === 408 || status === 429) {
+      return true;
+    }
+    return status >= 500;
+  }
+  /**
+   * Exponential backoff with equal jitter. The exponential ceiling is `baseDelayMs * 2^(attempt-1)`
+   * (capped at `maxDelayMs`); the actual delay is half that ceiling plus a random portion of the other
+   * half. The jitter spreads retries from many clients to avoid synchronized retry storms and needs no
+   * extra config. A `Retry-After` header, when present, acts as a lower bound.
+   */
+  backoffForAttempt(attempt, retryAfterMs) {
+    const retry = this.config.retry;
+    let ceiling = retry.baseDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+    if (retry.maxDelayMs > 0) {
+      ceiling = Math.min(ceiling, retry.maxDelayMs);
+    }
+    let delay = Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+    if (retryAfterMs !== null) {
+      delay = Math.max(delay, retryAfterMs);
+    }
+    return delay;
+  }
+  parseRetryAfter(response) {
+    const raw = response.headers?.["retry-after"];
+    if (!raw) {
+      return null;
+    }
+    const seconds = Number(raw);
+    if (!Number.isNaN(seconds)) {
+      return seconds * 1e3;
+    }
+    const dateMs = Date.parse(raw);
+    if (!Number.isNaN(dateMs)) {
+      return Math.max(0, dateMs - Date.now());
+    }
+    return null;
+  }
+  removeEntries(ids) {
+    if (ids.length === 0) {
+      return;
+    }
+    const idSet = new Set(ids);
+    this.pending = this.pending.filter((entry) => !idSet.has(entry.id));
+    void this.store?.remove(ids);
+  }
+  rescheduleIfPending() {
+    try {
+      if (this.destroyed) {
+        return;
+      }
+      if (this.timer) {
+        return;
+      }
+      if (this.pending.length === 0 && this.lowPending.length === 0 && this.lowsQueue.length === 0 && this.probeQueue.length === 0) {
+        return;
+      }
+      const now = Date.now();
+      if (this.getDuePending(now).length > 0 || this.lowPending.some((entry) => entry.flushAfter <= now) || this.lowsQueue.length > 0 || this.probeQueue.some((item) => item.flushAfter <= now)) {
+        this.scheduleFlush(this.flushInterval(), "timer");
+        return;
+      }
+      const nextDue = Math.min(
+        ...[...this.pending, ...this.lowPending, ...this.probeQueue].map((entry) => entry.flushAfter)
+      );
+      this.scheduleFlush(Math.max(0, nextDue - now), "backoff");
+    } catch (error) {
+      this.logger.error("Failed to reschedule queue flush", error);
+    }
+  }
+  setupLifecycleHooks() {
+    if (typeof window === "undefined") return;
+    this.onVisibilityChange = () => {
+      try {
+        this.writeLifecycleDebugOutput("cbo_visibility_change_debug");
+        if (document.visibilityState === "hidden" && this.config.tvc) {
+          this.flushSync("visibility-change");
+        }
+      } catch (error) {
+        this.logger.error("Unexpected error in queue flushSync", error);
+      }
+    };
+    this.onPageHide = () => {
+      try {
+        this.writeLifecycleDebugOutput("cbo_pagehide_debug");
+        if (this.config.tph) {
+          this.flushSync("pagehide");
+        }
+      } catch (error) {
+        this.logger.error("Unexpected error in queue flushSync", error);
+      }
+    };
+    window.addEventListener("visibilitychange", this.onVisibilityChange);
+    window.addEventListener("pagehide", this.onPageHide);
+  }
+  writeLifecycleDebugOutput(key) {
+    if (!this.debug || !this.storage) {
+      return;
+    }
+    const output = {
+      last_executed: Date.now(),
+      url: window.location.href
+    };
+    this.storage.setItem(key, output);
+  }
+  /**
+   * Synchronously flush pending events (and best-effort lows) during page unload.
+   *
+   * @remarks
+   * When `config.beaconKeepalive` is on, uses `sendBeacon` (falling back to fetch keepalive when
+   * the UA refuses the beacon); otherwise fires a fire-and-forget `fetch` keepalive request. The
+   * send is capped at one `batchSize` chunk per call (unload transports share an in-flight budget
+   * with the host app). With `config.durableOutbox` enabled, entries are NOT removed (they are
+   * resent on the next load and deduped server-side); otherwise the sent chunk is removed
+   * best-effort and a remainder keeps the next lifecycle signal flush-worthy.
+   * Deduplicated: a call with nothing newly enqueued since the last sync flush is a no-op — so of
+   * several unload signals in one navigation only the first one that finds something to send is
+   * recorded as the flush reason.
+   *
+   * @param reason What triggered the unload flush; defaults to a direct call by the host app.
+   */
+  flushKeepalive(reason = "manual") {
+    this.flushSync(reason);
+  }
+  flushSync(reason) {
+    const eventBytes = this.flushSyncEvents(reason);
+    if (reason === "pagehide" && this.probeQueue.length > 0) {
+      this.sendUnloadProbes(Math.min(UNLOAD_BUDGET_BYTES - eventBytes, UNLOAD_PROBE_MAX_BYTES), reason, true, true);
+    }
+  }
+  /** The event part of the unload flush; returns the serialized size of what it sent (0 = nothing). */
+  flushSyncEvents(reason) {
+    if (!this.dirtySinceSyncFlush) {
+      return 0;
+    }
+    const sessionId = this.sessionId;
+    const sessionEntries = this.pending.filter((entry) => entry.sessionId === sessionId);
+    const entries = sessionEntries.slice(0, this.batchSize);
+    const lowEntries = this.lowPending.filter((entry) => entry.sessionId === sessionId).slice(0, 100);
+    const lows = [...lowEntries.map((entry) => entry.event), ...this.takeLows(sessionId, 100 - lowEntries.length)];
+    this.prepareEvents(entries, reason);
+    const telemetry = this.takeTelemetry();
+    const deviceInfo = this.takeStandaloneDeviceInfo();
+    if (entries.length === 0 && lows.length === 0 && telemetry.length === 0 && !deviceInfo) {
+      this.dirtySinceSyncFlush = false;
+      return 0;
+    }
+    const batch = {
+      sessionId,
+      events: entries.map((entry) => entry.event),
+      sdk: this.sdk
+    };
+    if (lows.length > 0) {
+      batch.lows = lows;
+    }
+    if (telemetry.length > 0) {
+      batch.telemetry = telemetry;
+    }
+    if (deviceInfo) {
+      batch.deviceInfo = deviceInfo;
+    }
+    this.attachBatchMeta(batch, [...entries, ...lowEntries], reason);
+    if (lowEntries.length) batch.deliveryAck = true;
+    if (this.config.beaconKeepalive && this.transport.sendBeacon) {
+      if (!this.transport.sendBeacon(batch)) {
+        void this.transport.send(batch);
+      }
+    } else {
+      void this.transport.send(batch);
+    }
+    if (!this.config.durableOutbox) {
+      this.removeEntries(entries.map((entry) => entry.id));
+    }
+    this.dirtySinceSyncFlush = !this.config.durableOutbox && sessionEntries.length > entries.length;
+    return this.approximateSize(batch);
+  }
+  /** Serialized batch size for the unload budget; on failure assume the whole budget was used. */
+  approximateSize(batch) {
+    try {
+      return utf8Length(JSON.stringify(batch));
+    } catch {
+      return UNLOAD_BUDGET_BYTES;
+    }
+  }
+  /**
+   * Error situations:
+   *  - Timer clearance or event listener removal throws: log "Failed to destroy queue lifecycle hooks"
+   */
+  destroy() {
+    try {
+      this.destroyed = true;
+      this.clearTimer();
+      this.dropProbes(this.probeQueue.slice());
+      if (typeof window !== "undefined") {
+        if (this.onVisibilityChange) {
+          window.removeEventListener("visibilitychange", this.onVisibilityChange);
+        }
+        if (this.onPageHide) {
+          window.removeEventListener("pagehide", this.onPageHide);
+        }
+      }
+    } catch (error) {
+      this.logger.error("Failed to destroy queue lifecycle hooks", error);
+    }
+  }
+};
+export {
+  PROBE_BATCH_MAX_BYTES,
+  PROBE_BATCH_MAX_ITEMS,
+  PROBE_PAYLOAD_MAX_BYTES,
+  PROBE_QUEUE_MAX_BYTES,
+  PROBE_QUEUE_MAX_ITEMS,
+  RequestQueue,
+  UNLOAD_BUDGET_BYTES,
+  UNLOAD_PROBE_MAX_BYTES,
+  utf8Length
+};