@scalebun/react-native 1.0.2 → 1.0.4

package/src/analytics/EventTracker.ts

@@ -1,462 +1,489 @@
-/**
- * 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.
- */
-
-import { createStorageBackend, StorageBackend } from '../storage/StorageBackend';
-import { getDeviceId } from '../core/id/deviceId';
-import { logger } from '../core/logger/internalLogger';
-import { hmacSha256Hex } from '../crypto/hmacSha256';
-import { MAX_BATCH_EVENTS, clampBatchSize, batchIdempotencyKey } from './batching';
-import { subscribeAutomaticEvents } from './automaticEvents';
-
-// 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';
-
-const 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;
-
-export type EventPlatform = 'ios' | 'android' | 'web' | 'react_native';
-
-export interface EventTrackerConfig {
-    appId: string;
-    clientKey: string;
-    apiBaseUrl: string;
-    platform?: EventPlatform;
-    appVersion?: string;
-    osVersion?: string;
-    country?: string;
-    flushIntervalMs?: number;
-    batchSize?: number;
-    autoLifecycleEvents?: boolean;
-    /**
-     * Subscribe to the zero-instrumentation collector bus (screens, deep links,
-     * interactions, push and Engage outcomes). Default false so upgrading an
-     * existing `ScaleBun.init()` integration cannot silently increase volume.
-     * `ScaleBunProvider` opts in explicitly.
-     */
-    automaticEventTracking?: boolean;
-    /** Static context fields (sdk_version, device_model, manufacturer, language, timezone, network_type). */
-    context?: Record<string, any>;
-    /**
-     * Best-effort observer fired for every tracked event (incl. auto-lifecycle like
-     * first_open). Used by the SKAN CV manager to auto-apply conversion values. Must
-     * never throw; the tracker guards it regardless.
-     */
-    onEvent?: (eventName: string, revenue?: number) => void;
-    /**
-     * Canonical foreground session supplied by the shared session subsystem.
-     * Falls back to this tracker's local id when that subsystem is unavailable.
-     */
-    sessionIdProvider?: () => string | null | undefined;
-}
-
-export interface AdIdentifiers {
-    idfa?: string;
-    gaid?: string;
-    idfv?: string;
-    /** Phase 2: deferred deep-link click token, for deterministic install attribution. */
-    click_id?: string;
-}
-
-interface Envelope {
-    event_id: string;
-    event_name: string;
-    event_time: number;
-    app_id: string;
-    platform: string;
-    installation_id: string;
-    anonymous_id: string;
-    session_id?: string;
-    user_id?: string;
-    device_id?: string;
-    app_version?: string;
-    os_version?: string;
-    country?: string;
-    revenue?: number;
-    currency?: string;
-    properties?: Record<string, any>;
-    identifiers?: AdIdentifiers;
-    context?: Record<string, any>;
-}
-
-function uuid(): string {
-    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);
-    });
-}
-
-export class EventTracker {
-    private storage: StorageBackend;
-    private cfg: Required<Pick<EventTrackerConfig, 'appId' | 'clientKey' | 'apiBaseUrl'>> & EventTrackerConfig;
-    private installationId: string;
-    private anonymousId: string;
-    private sessionId: string;
-    private userId?: string;
-    private identifiers: AdIdentifiers = {};
-    private stamps: Record<string, any> = {};
-    private queue: Envelope[] = [];
-    private timer: any = null;
-    private flushing = false;
-    private failureCount = 0;
-    private started = false;
-    private automaticEventsUnsubscribe: (() => void) | null = null;
-
-    constructor(config: EventTrackerConfig) {
-        this.storage = createStorageBackend();
-        this.cfg = {
-            platform: 'react_native',
-            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()}`;
-        this.loadQueue();
-        this.loadClickId();
-    }
-
-    /** Stable per-install id (survives push-token rotation). */
-    public getInstallationId(): string {
-        return this.installationId;
-    }
-
-    // ─── lifecycle ───────────────────────────────────────────────────────────
-
-    start(): void {
-        if (this.started) return;
-        this.started = true;
-        if (this.cfg.automaticEventTracking) {
-            this.automaticEventsUnsubscribe = subscribeAutomaticEvents((event) => {
-                this.track(event.name, event.properties);
-            });
-        }
-        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.
-     */
-    private maybeAppUpdate(isFirstOpen: boolean): void {
-        const current = this.cfg.appVersion;
-        if (!current) return; // No version configured → nothing can be compared.
-        let previous: string | null = 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(): void {
-        this.sessionId = `sess-${uuid()}`;
-        this.track('session_start');
-    }
-
-    // ─── identity ────────────────────────────────────────────────────────────
-
-    identify(userId: string, traits?: Record<string, any>): void {
-        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(): void {
-        this.userId = undefined;
-    }
-
-    /** Set optional ad identifiers; they ride on every subsequent event. None required. */
-    setIdentifiers(ids: AdIdentifiers): void {
-        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: string, value: any): void {
-        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: string): void {
-        if (!clickId) return;
-        this.identifiers = { ...this.identifiers, click_id: clickId };
-        try { this.storage.set(K_CLICK_ID, clickId); } catch { /* no-throw */ }
-    }
-
-    // ─── tracking ────────────────────────────────────────────────────────────
-
-    track(eventName: string, properties?: Record<string, any>): void {
-        try {
-            this.enqueue(this.buildEnvelope(eventName, properties));
-            try { this.cfg.onEvent?.(eventName); } catch { /* no-throw */ }
-        } catch (err) {
-            logger.warn(`[ScaleBun.events] track failed: ${(err as Error)?.message}`);
-        }
-    }
-
-    trackPurchase(input: { revenue: number; currency: string; transactionId: string; [k: string]: any }): void {
-        const { revenue, currency, transactionId, ...rest } = input;
-        try {
-            const env = this.buildEnvelope('purchase', { ...rest, transaction_id: transactionId });
-            env.revenue = revenue;
-            env.currency = currency;
-            this.enqueue(env);
-            try { this.cfg.onEvent?.('purchase', revenue); } catch { /* no-throw */ }
-        } catch (err) {
-            logger.warn(`[ScaleBun.events] trackPurchase failed: ${(err as Error)?.message}`);
-        }
-    }
-
-    // ─── flush / transport ─────────────────────────────────────────────────────
-
-    async flush(): Promise<void> {
-        if (this.flushing || this.queue.length === 0) 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 = clampBatchSize(this.cfg.batchSize, DEFAULT_BATCH);
-        const batch = this.queue.slice(0, effectiveBatch);
-        try {
-            // Sign the exact bytes we send so the backend can tamper-detect the payload.
-            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 = 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': 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;
-            } else if (res.status >= 400 && res.status < 500 && res.status !== 429) {
-                // Permanent client error (bad key, malformed) — drop to avoid poison-looping.
-                logger.warn(`[ScaleBun.events] batch rejected (${res.status}); dropping ${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();
-        }
-    }
-
-    stop(): void {
-        this.automaticEventsUnsubscribe?.();
-        this.automaticEventsUnsubscribe = null;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
-        this.persistQueue();
-    }
-
-    // ─── internals ─────────────────────────────────────────────────────────────
-
-    private buildEnvelope(eventName: string, properties?: Record<string, any>): Envelope {
-        const ctx = this.cfg.context ?? {};
-        let canonicalSessionId: string | null | undefined;
-        try {
-            canonicalSessionId = this.cfg.sessionIdProvider?.();
-        } catch {
-            canonicalSessionId = null;
-        }
-        const env: Envelope = {
-            event_id: uuid(),
-            event_name: eventName,
-            event_time: Date.now(),
-            app_id: this.cfg.appId,
-            platform: this.cfg.platform ?? 'react_native',
-            installation_id: this.installationId,
-            anonymous_id: this.anonymousId,
-            session_id: canonicalSessionId || this.sessionId,
-            device_id: getDeviceId(),
-            // Phase 4: experiment stamps ride on every event; explicit props override.
-            properties: { ...this.stamps, ...(properties ?? {}) },
-            context: { sdk_version: ctx.sdk_version ?? '0.1.0', ...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;
-    }
-
-    private enqueue(env: Envelope): void {
-        this.queue.push(env);
-        if (this.queue.length > MAX_QUEUE) {
-            this.queue.splice(0, this.queue.length - MAX_QUEUE); // drop oldest
-        }
-        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();
-        }
-    }
-
-    private scheduleFlush(): void {
-        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 > 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);
-    }
-
-    private loadOrCreate(key: string): string {
-        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;
-    }
-
-    private persistQueue(): void {
-        try {
-            this.storage.set(K_QUEUE, JSON.stringify(this.queue));
-        } catch {
-            /* no-throw */
-        }
-    }
-
-    private loadQueue(): void {
-        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);
-            }
-        } catch {
-            this.queue = [];
-        }
-    }
-
-    private loadClickId(): void {
-        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,
-        };
-    }
-}
+/**
+ * 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.
+ */
+
+import { createStorageBackend, StorageBackend } from '../storage/StorageBackend';
+import { getDeviceId } from '../core/id/deviceId';
+import { logger } from '../core/logger/internalLogger';
+import { setNativeActiveSession } from '../features/crash/nativeCrashBridge';
+import { hmacSha256Hex } from '../crypto/hmacSha256';
+import { MAX_BATCH_EVENTS, clampBatchSize, batchIdempotencyKey } from './batching';
+import { subscribeAutomaticEvents } from './automaticEvents';
+
+// 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.
+ */
+export const 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;
+
+export type EventPlatform = 'ios' | 'android' | 'web' | 'react_native';
+
+export interface EventTrackerConfig {
+    appId: string;
+    clientKey: string;
+    apiBaseUrl: string;
+    platform?: EventPlatform;
+    appVersion?: string;
+    osVersion?: string;
+    country?: string;
+    flushIntervalMs?: number;
+    batchSize?: number;
+    autoLifecycleEvents?: boolean;
+    /**
+     * Subscribe to the zero-instrumentation collector bus (screens, deep links,
+     * interactions, push and Engage outcomes). Default false so upgrading an
+     * existing `ScaleBun.init()` integration cannot silently increase volume.
+     * `ScaleBunProvider` opts in explicitly.
+     */
+    automaticEventTracking?: boolean;
+    /** Static context fields (sdk_version, device_model, manufacturer, language, timezone, network_type). */
+    context?: Record<string, any>;
+    /**
+     * Best-effort observer fired for every tracked event (incl. auto-lifecycle like
+     * first_open). Used by the SKAN CV manager to auto-apply conversion values. Must
+     * never throw; the tracker guards it regardless.
+     */
+    onEvent?: (eventName: string, revenue?: number) => void;
+    /**
+     * Canonical foreground session supplied by the shared session subsystem.
+     * Falls back to this tracker's local id when that subsystem is unavailable.
+     */
+    sessionIdProvider?: () => string | null | undefined;
+}
+
+export interface AdIdentifiers {
+    idfa?: string;
+    gaid?: string;
+    idfv?: string;
+    /** Phase 2: deferred deep-link click token, for deterministic install attribution. */
+    click_id?: string;
+}
+
+interface Envelope {
+    event_id: string;
+    event_name: string;
+    event_time: number;
+    app_id: string;
+    platform: string;
+    installation_id: string;
+    anonymous_id: string;
+    session_id?: string;
+    user_id?: string;
+    device_id?: string;
+    app_version?: string;
+    os_version?: string;
+    country?: string;
+    revenue?: number;
+    currency?: string;
+    properties?: Record<string, any>;
+    identifiers?: AdIdentifiers;
+    context?: Record<string, any>;
+}
+
+function uuid(): string {
+    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);
+    });
+}
+
+export class EventTracker {
+    private storage: StorageBackend;
+    private cfg: Required<Pick<EventTrackerConfig, 'appId' | 'clientKey' | 'apiBaseUrl'>> & EventTrackerConfig;
+    private installationId: string;
+    private anonymousId: string;
+    private sessionId: string;
+    private userId?: string;
+    private identifiers: AdIdentifiers = {};
+    private stamps: Record<string, any> = {};
+    private queue: Envelope[] = [];
+    private timer: any = null;
+    private flushing = false;
+    private failureCount = 0;
+    private started = false;
+    private automaticEventsUnsubscribe: (() => void) | null = null;
+
+    constructor(config: EventTrackerConfig) {
+        this.storage = createStorageBackend();
+        this.cfg = {
+            platform: 'react_native',
+            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();
+    }
+
+    /** Stable per-install id (survives push-token rotation). */
+    public getInstallationId(): string {
+        return this.installationId;
+    }
+
+    // ─── lifecycle ───────────────────────────────────────────────────────────
+
+    start(): void {
+        if (this.started) return;
+        this.started = true;
+        if (this.cfg.automaticEventTracking) {
+            this.automaticEventsUnsubscribe = subscribeAutomaticEvents((event) => {
+                this.track(event.name, event.properties);
+            });
+        }
+        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.
+     */
+    private maybeAppUpdate(isFirstOpen: boolean): void {
+        const current = this.cfg.appVersion;
+        if (!current) return; // No version configured → nothing can be compared.
+        let previous: string | null = 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(): void {
+        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.
+     */
+    private publishSessionToNative(): void {
+        void setNativeActiveSession(this.sessionId);
+    }
+
+    // ─── identity ────────────────────────────────────────────────────────────
+
+    identify(userId: string, traits?: Record<string, any>): void {
+        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(): void {
+        this.userId = undefined;
+    }
+
+    /** Set optional ad identifiers; they ride on every subsequent event. None required. */
+    setIdentifiers(ids: AdIdentifiers): void {
+        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: string, value: any): void {
+        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: string): void {
+        if (!clickId) return;
+        this.identifiers = { ...this.identifiers, click_id: clickId };
+        try { this.storage.set(K_CLICK_ID, clickId); } catch { /* no-throw */ }
+    }
+
+    // ─── tracking ────────────────────────────────────────────────────────────
+
+    track(eventName: string, properties?: Record<string, any>): void {
+        try {
+            this.enqueue(this.buildEnvelope(eventName, properties));
+            try { this.cfg.onEvent?.(eventName); } catch { /* no-throw */ }
+        } catch (err) {
+            logger.warn(`[ScaleBun.events] track failed: ${(err as Error)?.message}`);
+        }
+    }
+
+    trackPurchase(input: { revenue: number; currency: string; transactionId: string; [k: string]: any }): void {
+        const { revenue, currency, transactionId, ...rest } = input;
+        try {
+            const env = this.buildEnvelope('purchase', { ...rest, transaction_id: transactionId });
+            env.revenue = revenue;
+            env.currency = currency;
+            this.enqueue(env);
+            try { this.cfg.onEvent?.('purchase', revenue); } catch { /* no-throw */ }
+        } catch (err) {
+            logger.warn(`[ScaleBun.events] trackPurchase failed: ${(err as Error)?.message}`);
+        }
+    }
+
+    // ─── flush / transport ─────────────────────────────────────────────────────
+
+    async flush(): Promise<void> {
+        if (this.flushing || this.queue.length === 0) 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 = clampBatchSize(this.cfg.batchSize, DEFAULT_BATCH);
+        const batch = this.queue.slice(0, effectiveBatch);
+        try {
+            // Sign the exact bytes we send so the backend can tamper-detect the payload.
+            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 = 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': 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;
+            } else if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+                // Permanent client error (bad key, malformed) — drop to avoid poison-looping.
+                logger.warn(`[ScaleBun.events] batch rejected (${res.status}); dropping ${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();
+        }
+    }
+
+    stop(): void {
+        this.automaticEventsUnsubscribe?.();
+        this.automaticEventsUnsubscribe = null;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.persistQueue();
+    }
+
+    // ─── internals ─────────────────────────────────────────────────────────────
+
+    private buildEnvelope(eventName: string, properties?: Record<string, any>): Envelope {
+        const ctx = this.cfg.context ?? {};
+        let canonicalSessionId: string | null | undefined;
+        try {
+            canonicalSessionId = this.cfg.sessionIdProvider?.();
+        } catch {
+            canonicalSessionId = null;
+        }
+        const env: Envelope = {
+            event_id: uuid(),
+            event_name: eventName,
+            event_time: Date.now(),
+            app_id: this.cfg.appId,
+            platform: this.cfg.platform ?? 'react_native',
+            installation_id: this.installationId,
+            anonymous_id: this.anonymousId,
+            session_id: canonicalSessionId || this.sessionId,
+            device_id: getDeviceId(),
+            // Phase 4: experiment stamps ride on every event; explicit props override.
+            properties: { ...this.stamps, ...(properties ?? {}) },
+            context: { sdk_version: ctx.sdk_version ?? '0.1.0', ...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;
+    }
+
+    private enqueue(env: Envelope): void {
+        this.queue.push(env);
+        if (this.queue.length > MAX_QUEUE) {
+            this.queue.splice(0, this.queue.length - MAX_QUEUE); // drop oldest
+        }
+        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();
+        }
+    }
+
+    private scheduleFlush(): void {
+        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 > 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);
+    }
+
+    private loadOrCreate(key: string): string {
+        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;
+    }
+
+    private persistQueue(): void {
+        try {
+            this.storage.set(K_QUEUE, JSON.stringify(this.queue));
+        } catch {
+            /* no-throw */
+        }
+    }
+
+    private loadQueue(): void {
+        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);
+            }
+        } catch {
+            this.queue = [];
+        }
+    }
+
+    private loadClickId(): void {
+        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,
+        };
+    }
+}