@scalebun-release/react-native 2.5.0

package/lib/commonjs/analytics/EventTracker.js

@@ -0,0 +1,598 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.K_INSTALLATION_ID = exports.EventTracker = void 0;
+var _StorageBackend = require("../storage/StorageBackend");
+var _device = require("../core/context/device");
+var _deviceId = require("../core/id/deviceId");
+var _version = require("../core/constants/version");
+var _internalLogger = require("../core/logger/internalLogger");
+var _nativeCrashBridge = require("../features/crash/nativeCrashBridge");
+var _hmacSha = require("../crypto/hmacSha256");
+var _batching = require("./batching");
+var _automaticEvents = require("./automaticEvents");
+var _revenue = require("./revenue");
+var _subscription = require("./subscription");
+var _quotaState = require("../config/quotaState");
+/**
+ * ScaleBun SDK — Phase 1 Envelope Event Tracker
+ *
+ * A small, self-contained lane that emits the Phase 1 event envelope to
+ * `POST {apiBaseUrl}/batch`. Deliberately decoupled from the replay/analytics
+ * pipeline so it can ship without touching it.
+ *
+ * Responsibilities:
+ *  - stable installation_id + anonymous_id (persisted via StorageBackend)
+ *  - session_id per launch
+ *  - first_open exactly once per installation
+ *  - app_open / session_start on start()
+ *  - client-side event_id
+ *  - offline queue (persisted) + batch flush + exponential backoff
+ *  - never throws / never crashes the host app on network failure
+ *  - optional idfa / gaid / idfv identifiers (set, never required)
+ *
+ * Public methods mirror the Phase 1 contract: track / identify / trackPurchase / flush.
+ */
+
+// Phase 5.4: signing-scheme version. The backend tamper-checks signed batches and
+// treats an unsigned/invalid batch from a signing-capable SDK as a fraud signal.
+const SDK_SIGNING_VERSION = '1';
+
+/**
+ * Exported because this is THE canonical per-install identity key for the whole
+ * SDK. The OTA lane used to demand a caller-supplied installationId instead of
+ * reading this one, which put OTA telemetry in its own id namespace — every
+ * join from OTA to CDP (blast radius, MRR-at-risk, churn) matched by luck.
+ * One install, one id, every lane.
+ */
+const K_INSTALLATION_ID = exports.K_INSTALLATION_ID = 'scalebun_installation_id';
+const K_ANONYMOUS_ID = 'scalebun_anonymous_id';
+const K_FIRST_OPEN = 'scalebun_first_open_done';
+/** Last app version seen on this device — the baseline app_update compares against. */
+const K_APP_VERSION = 'scalebun_last_app_version';
+const K_QUEUE = 'scalebun_envelope_queue';
+const K_CLICK_ID = 'scalebun_attribution_click_id';
+const DEFAULT_FLUSH_MS = 5000;
+const DEFAULT_BATCH = 50;
+const MAX_QUEUE = 2000;
+const MAX_BACKOFF_MS = 60_000;
+
+/** Live event-lane diagnostics. Counters reset when the SDK process creates a new tracker. */
+
+function uuid() {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    const v = c === 'x' ? r : r & 0x3 | 0x8;
+    return v.toString(16);
+  });
+}
+class EventTracker {
+  identifiers = {};
+  stamps = {};
+  queue = [];
+  timer = null;
+  flushing = false;
+  failureCount = 0;
+  droppedCount = 0;
+  started = false;
+  automaticEventsUnsubscribe = null;
+  quotaUnsubscribe = null;
+  constructor(config) {
+    this.storage = (0, _StorageBackend.createStorageBackend)();
+    this.cfg = {
+      platform: (0, _device.resolveEventPlatform)(),
+      flushIntervalMs: DEFAULT_FLUSH_MS,
+      batchSize: DEFAULT_BATCH,
+      autoLifecycleEvents: true,
+      automaticEventTracking: false,
+      ...config
+    };
+    this.installationId = this.loadOrCreate(K_INSTALLATION_ID);
+    this.anonymousId = this.loadOrCreate(K_ANONYMOUS_ID);
+    this.sessionId = `sess-${uuid()}`;
+    // Published immediately, before anything else runs — a crash can happen on the very next
+    // line, and native must already know which session owns it.
+    this.publishSessionToNative();
+    this.loadQueue();
+    this.loadClickId();
+    // Quota (contract v1): an `events` block purges the queue — memory AND the persisted copy —
+    // the moment it starts, whichever lane discovered it (/config, this lane's /v1/batch body, or a
+    // 402 on the session /events lane).
+    this.quotaUnsubscribe = _quotaState.quotaState.subscribe((feature, blocked) => {
+      if (feature === 'events' && blocked) this.purgeForQuota();
+    });
+  }
+
+  /** Drop every queued envelope: the server would refuse them and must not be retried. */
+  purgeForQuota() {
+    if (this.queue.length === 0) return;
+    _internalLogger.logger.warn(`[ScaleBun.events] events quota exceeded — dropping ${this.queue.length} queued event(s)`);
+    this.droppedCount += this.queue.length;
+    this.queue = [];
+    this.persistQueue();
+  }
+
+  /** Stable per-install id (survives push-token rotation). */
+  getInstallationId() {
+    return this.installationId;
+  }
+
+  /** Events waiting for delivery and events intentionally dropped by bounded validation/queues. */
+  get stats() {
+    return {
+      pending: this.queue.length,
+      dropped: this.droppedCount
+    };
+  }
+
+  // ─── lifecycle ───────────────────────────────────────────────────────────
+
+  start() {
+    if (this.started) return;
+    this.started = true;
+    if (this.cfg.automaticEventTracking) {
+      this.automaticEventsUnsubscribe = (0, _automaticEvents.subscribeAutomaticEvents)(event => {
+        this.track(event.name, event.properties, event.timestamp);
+      });
+    }
+    if (this.cfg.autoLifecycleEvents) {
+      // first_open: exactly once per installation (guarded locally; the backend
+      // also enforces once-per-installation as the source of truth).
+      const isFirstOpen = this.storage.get(K_FIRST_OPEN) !== '1';
+      if (isFirstOpen) {
+        this.track('first_open');
+        this.storage.set(K_FIRST_OPEN, '1');
+      }
+      // app_update — the event release-adoption funnels are built on, and it did not exist.
+      // `first_open` marked a NEW install and nothing marked an UPGRADE, so "did users who moved
+      // to 2.2 retain better" and "how fast does a release roll out" were both unanswerable.
+      // Skipped on a first open: that install has no previous version to have come from.
+      this.maybeAppUpdate(isFirstOpen);
+      this.track('session_start');
+      this.track('app_open');
+    }
+    this.scheduleFlush();
+  }
+
+  /**
+   * Emit `app_update` when the running app version differs from the one last seen on this device.
+   *
+   * The last-seen version is stored regardless of the outcome, so the very first run after this
+   * feature ships records a baseline WITHOUT claiming an upgrade happened — the alternative
+   * (treating "no stored version" as an update) would fire a false `app_update` for every existing
+   * installation on the day it rolls out.
+   */
+  maybeAppUpdate(isFirstOpen) {
+    const current = this.cfg.appVersion;
+    if (!current) return; // No version configured → nothing can be compared.
+    let previous = null;
+    try {
+      previous = this.storage.get(K_APP_VERSION) ?? null;
+    } catch {
+      return; // Storage unavailable → stay silent rather than guess.
+    }
+    try {
+      this.storage.set(K_APP_VERSION, current);
+    } catch {
+      /* best-effort — a failed write just means we may re-detect next launch */
+    }
+    if (isFirstOpen || !previous || previous === current) return;
+    this.track('app_update', {
+      previous_version: previous,
+      current_version: current
+    });
+  }
+
+  /** Start a fresh session (e.g. after the app returns from a long background). */
+  newSession() {
+    this.sessionId = `sess-${uuid()}`;
+    this.publishSessionToNative();
+    this.track('session_start');
+  }
+
+  /**
+   * Hand the live session id to the native crash layer.
+   *
+   * Called at EVERY point the id changes — construction and rollover — because a crash-safe copy
+   * that is one session stale is worse than none: it would confidently attribute a crash to a
+   * session that had already ended.
+   *
+   * Fire-and-forget. Native persists it synchronously on its own side; a failure here degrades a
+   * recovered crash to unattributed, which is exactly the behaviour before this existed, and must
+   * never be able to fail a session start.
+   */
+  publishSessionToNative() {
+    /*
+     * Only when THIS tracker's id is the one the backend knows.
+     *
+     * With a sessionIdProvider the ingestion session (`ses-…`, opened by BackendSessionAdapter)
+     * owns every row, and that adapter publishes its own id to native. This tracker's `sess-…` is
+     * a local fallback no backend row ever carries: published here, it stamped every native crash
+     * with an id the errors endpoint answers 404 for, and the SDK dropped the crash as a permanent
+     * failure. Every crash from an app with eventTracking on (le-garage) was lost that way.
+     */
+    if (this.cfg.sessionIdProvider) return;
+    void (0, _nativeCrashBridge.setNativeActiveSession)(this.sessionId);
+  }
+
+  // ─── identity ────────────────────────────────────────────────────────────
+
+  identify(userId, traits) {
+    this.userId = userId;
+    // Emit a lightweight login event carrying user_id + traits so the backend
+    // links user_id → profile immediately (subsequent events also carry user_id).
+    this.track('login', traits ?? {});
+  }
+
+  /** Stop attaching an identified user after logout; installation identity remains. */
+  clearIdentity() {
+    this.userId = undefined;
+  }
+
+  /** Set optional ad identifiers; they ride on every subsequent event. None required. */
+  setIdentifiers(ids) {
+    this.identifiers = {
+      ...this.identifiers,
+      ...ids
+    };
+  }
+
+  /**
+   * Phase 4: stamp a persistent property onto every subsequent event (e.g. an
+   * experiment assignment `experiment_<key>=<variant>`). Explicit per-event
+   * properties win over a stamp with the same key.
+   */
+  stamp(key, value) {
+    this.stamps[key] = value;
+  }
+
+  /**
+   * Phase 2: record a deferred deep-link click token (from a tracking-link landing
+   * or install referrer). It rides on `identifiers.click_id` of every subsequent
+   * event — notably first_open — so the backend attributes the install deterministically.
+   * Persisted so it survives the click→install→open gap. Call BEFORE start() ideally.
+   */
+  setAttributionClickId(clickId) {
+    if (!clickId) return;
+    this.identifiers = {
+      ...this.identifiers,
+      click_id: clickId
+    };
+    try {
+      this.storage.set(K_CLICK_ID, clickId);
+    } catch {/* no-throw */}
+  }
+
+  // ─── tracking ────────────────────────────────────────────────────────────
+
+  track(eventName, properties, timestamp) {
+    try {
+      this.enqueue(this.buildEnvelope(eventName, properties, timestamp));
+      try {
+        this.cfg.onEvent?.(eventName);
+      } catch {/* no-throw */}
+    } catch (err) {
+      _internalLogger.logger.warn(`[ScaleBun.events] track failed: ${err?.message}`);
+    }
+  }
+
+  /**
+   * A purchase, normalized through the shared revenue rules.
+   *
+   * This used to spread the caller's object straight onto the envelope, which
+   * made mobile disagree with web on the two things a revenue report is built
+   * from: a refund kept whatever sign the caller gave it (so an iOS refund
+   * ADDED to gross revenue and to the customer's lifetime value), and
+   * `productId` never became the `product_id` the rollup groups plans by, so
+   * every mobile sale landed in "Unattributed". See revenue.ts for the full
+   * list and why the property names are the web SDK's.
+   *
+   * A rejected input is DROPPED, with a dev-time warning. A purchase with no
+   * transaction id cannot be deduplicated, and enqueuing it anyway is how one
+   * retried network call becomes two sales.
+   */
+  trackPurchase(input) {
+    try {
+      const n = (0, _revenue.normalizeRevenue)(input);
+      if (!n) {
+        this.droppedCount++;
+        __DEV__ && _internalLogger.logger.warn('[ScaleBun.events] trackPurchase dropped: revenue, currency and transactionId are all required.');
+        return;
+      }
+      const env = this.buildEnvelope('purchase', n.props);
+      env.revenue = n.revenue;
+      env.currency = n.currency;
+      this.enqueue(env);
+      // SKAN conversion values are driven by what was EARNED, so a refund
+      // must not raise one. The normalized (signed) amount is the honest input.
+      try {
+        this.cfg.onEvent?.('purchase', n.revenue);
+      } catch {/* no-throw */}
+    } catch (err) {
+      _internalLogger.logger.warn(`[ScaleBun.events] trackPurchase failed: ${err?.message}`);
+    }
+  }
+
+  /**
+   * Record an event-sourced subscription state change for the recurring-
+   * revenue ledger. This bypasses generic `$` event routing deliberately:
+   * `$subscription` belongs on the durable analytics `/batch` lane.
+   */
+  trackSubscription(input) {
+    try {
+      const properties = (0, _subscription.normalizeSubscription)(input);
+      if (!properties) {
+        this.droppedCount++;
+        __DEV__ && _internalLogger.logger.warn('[ScaleBun.events] trackSubscription dropped: subscriptionId, status and a valid plan for price-setting states are required.');
+        return;
+      }
+      this.enqueue(this.buildEnvelope('$subscription', properties));
+      try {
+        this.cfg.onEvent?.('$subscription');
+      } catch {/* no-throw */}
+    } catch (err) {
+      _internalLogger.logger.warn(`[ScaleBun.events] trackSubscription failed: ${err?.message}`);
+    }
+  }
+
+  // ─── flush / transport ─────────────────────────────────────────────────────
+
+  async flush() {
+    if (this.flushing || this.queue.length === 0) return;
+    // Quota, send-time: never POST while `events` is blocked (covers a queue restored from disk
+    // before the block was known and anything enqueued in the same tick).
+    if (_quotaState.quotaState.isBlocked('events')) {
+      this.purgeForQuota();
+      return;
+    }
+    this.flushing = true;
+    // Wave 1 (§2F.1): never emit a batch larger than the server maximum, else
+    // the backend rejects the whole request (413 BATCH_TOO_LARGE) and we would
+    // drop every event in it. Clamp the configured size into [1, MAX_BATCH_EVENTS].
+    const effectiveBatch = (0, _batching.clampBatchSize)(this.cfg.batchSize, DEFAULT_BATCH);
+    const batch = this.queue.slice(0, effectiveBatch);
+    try {
+      // WHAT THIS SIGNATURE IS, AND WHAT IT IS NOT.
+      //
+      // This used to be described as letting "the backend tamper-detect
+      // the payload", which overstates it to the point of being wrong.
+      // The HMAC key is `clientKey` — the same value sent beside it in
+      // `x-scalebun-client-key`, and a value that ships inside every
+      // installed app, extractable by anyone who unzips an APK. A MAC
+      // whose key travels with the message and is public by construction
+      // proves nothing about who sent it: anyone can compute a valid one.
+      //
+      // What it DOES buy is integrity in transit against non-adversarial
+      // corruption, and a cheap filter for junk traffic. Treat `clientKey`
+      // as a publishable identifier (like a Stripe publishable key), never
+      // as a trust boundary. Authenticity that actually holds has to come
+      // from something the client cannot forge — server-side rate limits
+      // and anomaly detection per key, short-lived device tokens, or
+      // platform attestation (Play Integrity / App Attest).
+      //
+      // Contrast with OTA bundle signing (features/ota/signature.ts),
+      // which is asymmetric: the private half never leaves the publisher,
+      // so a valid signature there IS proof of origin.
+      const payload = JSON.stringify({
+        events: batch
+      });
+      // Wave 2 (§2F.2): a stable idempotency key over the batch's event ids so a
+      // retry after a timeout/disconnect replays the first response instead of
+      // re-counting accepts. Same leading events → same key across retries.
+      const idempotencyKey = (0, _batching.batchIdempotencyKey)(batch.map(e => e.event_id));
+      const res = await fetch(`${this.cfg.apiBaseUrl}/batch`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-scalebun-client-key': this.cfg.clientKey,
+          'x-scalebun-signature': (0, _hmacSha.hmacSha256Hex)(this.cfg.clientKey, payload),
+          'x-scalebun-sdk-version': SDK_SIGNING_VERSION,
+          'Idempotency-Key': idempotencyKey
+        },
+        body: payload
+      });
+      if (res.ok) {
+        // Drop the sent batch; reset backoff.
+        this.queue.splice(0, batch.length);
+        this.persistQueue();
+        this.failureCount = 0;
+        // Contract v1 §2c: a 200 whose body says `quota.events.blocked` — the counts in it are
+        // truthful (dropped events are NOT retried). Recording the block purges the rest.
+        await this.noteQuota(res, false);
+      } else if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+        // A 402 quota_exceeded(events) is a permanent refusal too; record the block first.
+        if (res.status === 402) await this.noteQuota(res, true);
+        // Permanent client error (bad key, malformed) — drop to avoid poison-looping.
+        _internalLogger.logger.warn(`[ScaleBun.events] batch rejected (${res.status}); dropping ${batch.length}`);
+        this.droppedCount += batch.length;
+        this.queue.splice(0, batch.length);
+        this.persistQueue();
+        this.failureCount = 0;
+      } else {
+        this.failureCount++;
+      }
+    } catch {
+      // Network failure — keep events queued, back off. Never throws.
+      this.failureCount++;
+    } finally {
+      this.flushing = false;
+      this.scheduleFlush();
+    }
+  }
+
+  /** Read a /v1/batch response for a quota refusal. Never throws. */
+  async noteQuota(res, isRefusal) {
+    try {
+      if (typeof res?.json !== 'function') return;
+      const body = await res.json();
+      const headers = res.headers;
+      if (isRefusal) (0, _quotaState.noteQuotaResponse)(res.status, body, headers);else (0, _quotaState.noteBatchQuota)(body, headers);
+    } catch {
+      /* empty / non-JSON body */
+    }
+  }
+  stop() {
+    this.automaticEventsUnsubscribe?.();
+    this.automaticEventsUnsubscribe = null;
+    this.quotaUnsubscribe?.();
+    this.quotaUnsubscribe = null;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.persistQueue();
+  }
+
+  /**
+   * Fold in device facts that were not knowable at init.
+   *
+   * `Platform.constants` answers Android synchronously, so its model and manufacturer ride the
+   * very first event. iOS exposes neither there — only the native bridge knows, and the bridge is
+   * async and may not be installed at all. Without this the iOS half of every install reported no
+   * model whatsoever.
+   *
+   * `buildEnvelope` reads `cfg.context` per event, so applying it here reaches every event from
+   * the next one onward. Detected keys WIN over whatever the integrator configured, for the same
+   * reason `mergeDeviceContext` inverts the usual precedence: a measurement must not be
+   * overridable by a guess. Empty patches are ignored so a bridge that answered with nothing
+   * cannot blank a value the static path already found.
+   */
+  applyDetectedContext(patch) {
+    if (!patch || Object.keys(patch).length === 0) return;
+    this.cfg.context = {
+      ...(this.cfg.context ?? {}),
+      ...patch
+    };
+  }
+
+  // ─── internals ─────────────────────────────────────────────────────────────
+
+  buildEnvelope(eventName, properties, timestamp) {
+    const ctx = this.cfg.context ?? {};
+    let canonicalSessionId;
+    try {
+      canonicalSessionId = this.cfg.sessionIdProvider?.();
+    } catch {
+      canonicalSessionId = null;
+    }
+    const env = {
+      event_id: uuid(),
+      event_name: eventName,
+      event_time: timestamp ?? Date.now(),
+      app_id: this.cfg.appId,
+      platform: this.cfg.platform ?? (0, _device.resolveEventPlatform)(),
+      installation_id: this.installationId,
+      anonymous_id: this.anonymousId,
+      session_id: canonicalSessionId || this.sessionId,
+      device_id: (0, _deviceId.getDeviceId)(),
+      // Phase 4: experiment stamps ride on every event; explicit props override.
+      properties: {
+        ...this.stamps,
+        ...(properties ?? {})
+      },
+      context: {
+        sdk_version: ctx.sdk_version ?? _version.SDK_VERSION,
+        ...ctx
+      }
+    };
+    if (this.userId) env.user_id = this.userId;
+    if (this.cfg.appVersion) env.app_version = this.cfg.appVersion;
+    if (this.cfg.osVersion) env.os_version = this.cfg.osVersion;
+    if (this.cfg.country) env.country = this.cfg.country;
+    if (Object.keys(this.identifiers).length > 0) env.identifiers = this.identifiers;
+    return env;
+  }
+  enqueue(env) {
+    // Quota, capture-time: an `events` block stops capture at the source.
+    if (_quotaState.quotaState.isBlocked('events')) {
+      this.droppedCount++;
+      return;
+    }
+    this.queue.push(env);
+    if (this.queue.length > MAX_QUEUE) {
+      const over = this.queue.length - MAX_QUEUE;
+      this.queue.splice(0, over); // drop oldest
+      this.droppedCount += over;
+    }
+    this.persistQueue();
+    // Flush eagerly once we have a full batch.
+    if (this.queue.length >= (this.cfg.batchSize ?? DEFAULT_BATCH)) {
+      this.flush().catch(() => {});
+    } else if (this.started) {
+      // Re-arm the flush pump. flush() stops rescheduling once the queue
+      // drains (it early-returns on an empty queue), so a later sparse event
+      // must restart the timer or it would sit unsent until the next launch.
+      this.scheduleFlush();
+    }
+  }
+  scheduleFlush() {
+    if (this.timer) clearTimeout(this.timer);
+    const base = this.cfg.flushIntervalMs ?? DEFAULT_FLUSH_MS;
+    // A backlog larger than one server-max batch is drained promptly (one chunk
+    // per tick) so a 5,000-event queue doesn't trickle out at one batch/interval.
+    const backlogRemaining = this.failureCount === 0 && this.queue.length > _batching.MAX_BATCH_EVENTS;
+    const delay = this.failureCount > 0 ? Math.min(base * Math.pow(2, this.failureCount), MAX_BACKOFF_MS) + Math.random() * 250 : backlogRemaining ? 0 : base;
+    this.timer = setTimeout(() => {
+      this.flush().catch(() => {});
+    }, delay);
+  }
+  loadOrCreate(key) {
+    try {
+      const existing = this.storage.get(key);
+      if (existing) return existing;
+    } catch {
+      /* fall through */
+    }
+    const id = uuid();
+    try {
+      this.storage.set(key, id);
+    } catch {
+      /* memory-only fallback */
+    }
+    return id;
+  }
+  persistQueue() {
+    try {
+      this.storage.set(K_QUEUE, JSON.stringify(this.queue));
+    } catch {
+      /* no-throw */
+    }
+  }
+  loadQueue() {
+    try {
+      const raw = this.storage.get(K_QUEUE);
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) this.queue = parsed.slice(-MAX_QUEUE);
+      }
+      // Quota: a queue restored from a previous launch while `events` is (persisted as) blocked
+      // is purged, not held for later — it was captured under an allowance that is spent.
+      if (this.queue.length > 0 && _quotaState.quotaState.isBlocked('events')) this.purgeForQuota();
+    } catch {
+      this.queue = [];
+    }
+  }
+  loadClickId() {
+    try {
+      const cid = this.storage.get(K_CLICK_ID);
+      if (cid) this.identifiers.click_id = cid;
+    } catch {
+      /* no-throw */
+    }
+  }
+
+  // ─── introspection (for demo/debug) ────────────────────────────────────────
+
+  get ids() {
+    return {
+      installationId: this.installationId,
+      anonymousId: this.anonymousId,
+      sessionId: this.sessionId,
+      userId: this.userId
+    };
+  }
+}
+exports.EventTracker = EventTracker;
+//# sourceMappingURL=EventTracker.js.map

package/lib/commonjs/analytics/automaticEvents.js

@@ -0,0 +1,71 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.emitAutomaticEvent = emitAutomaticEvent;
+exports.resetAutomaticEventsForTests = resetAutomaticEventsForTests;
+exports.subscribeAutomaticEvents = subscribeAutomaticEvents;
+/**
+ * Canonical automatic-event bus.
+ *
+ * Every zero-instrumentation collector publishes here. EventTracker subscribes
+ * once and turns the observations into the same signed `/batch` envelopes used
+ * by public `track()` calls. Keeping collectors transport-agnostic prevents
+ * lifecycle/navigation/push/Engage from growing parallel ingestion lanes.
+ */
+
+const listeners = new Set();
+const pending = [];
+const MAX_PENDING = 50;
+function compactProperties(properties) {
+  const out = {
+    capture_source: 'automatic'
+  };
+  for (const [key, value] of Object.entries(properties ?? {})) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+function emitAutomaticEvent(name, properties, timestamp) {
+  const event = {
+    name,
+    properties: compactProperties(properties),
+    timestamp
+  };
+  if (listeners.size === 0) {
+    pending.push(event);
+    if (pending.length > MAX_PENDING) pending.shift();
+    return;
+  }
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } catch {
+      // Automatic capture must never affect the host application.
+    }
+  }
+}
+function subscribeAutomaticEvents(listener) {
+  listeners.add(listener);
+  if (pending.length > 0) {
+    const buffered = pending.splice(0, pending.length);
+    for (const event of buffered) {
+      try {
+        listener(event);
+      } catch {
+        // A bad observer cannot poison later automatic events.
+      }
+    }
+  }
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test-only reset; intentionally not exported from the package entry point. */
+function resetAutomaticEventsForTests() {
+  listeners.clear();
+  pending.splice(0, pending.length);
+}
+//# sourceMappingURL=automaticEvents.js.map