@scalebun-release/web 2.2.2

package/dist/features/analytics/AnalyticsFeature.js

@@ -0,0 +1,785 @@
+import { uuid, now, getReplayCoord, scrubProps, SDK_VERSION } from '../../core/index.js';
+import { evaluateEvent } from './governance.js';
+import { keepEvent } from './sampler.js';
+import { PersistentBuffer } from '../../storage/idb.js';
+import { Backoff, isOnline, onOnline } from '../../core/retry.js';
+import { capBytes, freshOnly } from '../../core/prune.js';
+const BATCH_MAX = 50;
+const FLUSH_MS = 5000;
+const QUEUE_CAP = 2000; // bound memory; drop oldest beyond this
+const K_ANON = 'scalebun_anonymous_id';
+/**
+ * The IDENTIFIED user, persisted beside the anonymous id.        (SESSIONS-REAL-DATA-PLAN §2b)
+ *
+ * `userId` used to be an in-memory field only, so the identity died with the document: an app that
+ * called identify() at login went back to Anonymous on the next page load, and every session after
+ * the first was unattributed. The anonymous id was already persisted — this is the half that was
+ * missing. Cleared by reset() so the next user is never attributed to the previous one.
+ */
+const K_UID = 'scalebun_user_id';
+const K_SUPER = 'scalebun_super_props'; // A1 — registered global properties, merged into every event
+const K_GROUPS = 'scalebun_groups'; // A1 — B2B group memberships { groupType: groupKey }
+// W1b — install attribution (RN storage-key parity).
+const K_INSTALL = 'scalebun_installation_id';
+const K_FIRSTOPEN = 'scalebun_first_open_done';
+const K_CLICK = 'scalebun_attribution_click_id';
+const K_ATTR = 'scalebun_attribution'; // W6.0 — persisted FIRST-TOUCH web acquisition (referrer/utm/landing)
+const CLICK_RE = /^[0-9a-f]{16,64}$/i; // our redirect issues a 32-hex click id; stay tolerant
+const UTM_KEYS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
+/**
+ * W6.0 — capture FIRST-TOUCH web acquisition once and persist it (referrer + UTM + landing page + ad
+ * click ids), mirroring the "initial UTM as super-property" pattern. Merged into every event's props so
+ * any session groups by source/medium/campaign/channel server-side. Never overwrites an existing first
+ * touch (a later direct visit must not erase the acquiring campaign). Referrer query is stripped (PII).
+ */
+function captureWebAttribution() {
+    try {
+        if (typeof localStorage !== 'undefined') {
+            const raw = localStorage.getItem(K_ATTR);
+            if (raw) {
+                const v = JSON.parse(raw);
+                if (v && typeof v === 'object')
+                    return { props: v, isNew: false };
+            }
+        }
+    }
+    catch {
+        /* storage disabled / corrupt → recapture */
+    }
+    const out = {};
+    try {
+        if (typeof location !== 'undefined') {
+            const url = new URL(location.href);
+            for (const k of UTM_KEYS) {
+                const v = url.searchParams.get(k);
+                if (v)
+                    out[k] = v.slice(0, 200);
+            }
+            for (const k of ['fbclid', 'gclid']) {
+                const v = url.searchParams.get(k);
+                if (v)
+                    out[k] = v.slice(0, 512);
+            }
+        }
+        if (typeof document !== 'undefined' && document.referrer) {
+            try {
+                const ref = new URL(document.referrer);
+                /*
+                 * A SAME-HOST referrer is not acquisition. It is the previous page of this visit.
+                 *
+                 * Every navigation inside a site sets `document.referrer` to the page you came from, so a
+                 * reader moving from /doctors to /sign-up arrives carrying a referrer for the site they are
+                 * already on. Sent as an acquisition signal it classifies under rule 91 — "any referrer
+                 * domain that is not a search engine or social network" — as REFERRAL.
+                 *
+                 * Measured on production before this: 4,641 of one site's 4,669 Referral touchpoints in a
+                 * 30-day window had no source and no medium, landing on `/`, `/sign-in` and `/patient/main`
+                 * — its own pages. Direct collapsed to 48 sessions against roughly 4,200 real ones, and
+                 * Referral was inflated eightfold. The site's own top three referrers were itself.
+                 *
+                 * Dropped here rather than fixed in the classifier because the classifier cannot know: it
+                 * receives a hostname with nothing to compare it against, while the browser knows perfectly
+                 * well which site it is on.
+                 */
+                const self = typeof location !== 'undefined' ? location.hostname : null;
+                if (!self || ref.hostname !== self) {
+                    out.referrer = (ref.origin + ref.pathname).slice(0, 512); // strip query/hash → no referrer PII
+                    out.referrer_domain = ref.hostname;
+                }
+            }
+            catch {
+                out.referrer = document.referrer.split('?')[0].slice(0, 512);
+            }
+        }
+    }
+    catch {
+        /* malformed URL */
+    }
+    // Attribution = the ACQUISITION touch. A direct visit (no referrer/utm/click) has none, so we stamp
+    // nothing (entry/landing for every session is derived from $pageview downstream). Only when there IS a
+    // signal do we add the campaign's landing page + persist it as the durable first touch.
+    if (!out.referrer && !out.utm_source && !out.fbclid && !out.gclid)
+        return { props: {}, isNew: false };
+    try {
+        if (typeof location !== 'undefined')
+            out.landing_url = location.pathname.slice(0, 512);
+        if (typeof localStorage !== 'undefined')
+            localStorage.setItem(K_ATTR, JSON.stringify(out));
+    }
+    catch {
+        /* storage disabled — rides this session only */
+    }
+    return { props: out, isNew: true }; // freshly acquired → the caller records the touchpoint once
+}
+// Distinct IndexedDB record so unsent /batch events survive a reload/crash — independent of the
+// session pipeline's 'pending' record. Backend dedups by (appId, event_id), so reload re-sends are safe.
+const IDB_KEY = 'pending-analytics';
+/** Persisted identified-user id; undefined when anonymous or storage is unavailable. */
+function loadUid() {
+    try {
+        if (typeof localStorage !== 'undefined')
+            return localStorage.getItem(K_UID) || undefined;
+    }
+    catch {
+        /* storage disabled → identity lasts this document only */
+    }
+    return undefined;
+}
+function saveUid(uid) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        if (uid)
+            localStorage.setItem(K_UID, uid);
+        else
+            localStorage.removeItem(K_UID);
+    }
+    catch {
+        /* storage disabled */
+    }
+}
+function newAnonId() {
+    return `anon_${uuid()}`;
+}
+/** Read a persisted JSON record (super-props / groups); returns {} on any failure. */
+function loadJson(key) {
+    try {
+        if (typeof localStorage !== 'undefined') {
+            const raw = localStorage.getItem(key);
+            if (raw) {
+                const v = JSON.parse(raw);
+                if (v && typeof v === 'object')
+                    return v;
+            }
+        }
+    }
+    catch {
+        /* storage disabled / corrupt */
+    }
+    return {};
+}
+function saveJson(key, value) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        if (Object.keys(value).length)
+            localStorage.setItem(key, JSON.stringify(value));
+        else
+            localStorage.removeItem(key);
+    }
+    catch {
+        /* storage disabled — in-memory copy still applies this session */
+    }
+}
+// A6 — cross-subdomain sharing: a cookie scoped to `cookieDomain` (e.g. '.example.com') lets
+// app./www./shop. resolve to ONE anonymous id. localStorage stays the per-origin fallback.
+function readCookie(name) {
+    try {
+        if (typeof document === 'undefined')
+            return null;
+        const m = document.cookie.match(new RegExp('(?:^|; )' + name + '=([^;]*)'));
+        const v = m?.[1];
+        return v != null ? decodeURIComponent(v) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCookie(name, value, domain) {
+    try {
+        if (typeof document === 'undefined')
+            return;
+        const parts = [`${name}=${encodeURIComponent(value)}`, 'path=/', 'max-age=31536000', 'SameSite=Lax'];
+        if (domain)
+            parts.push(`domain=${domain}`);
+        document.cookie = parts.join('; ');
+    }
+    catch {
+        /* cookies disabled */
+    }
+}
+/**
+ * W1b — resolve the stable INSTALL id (distinct from the device id, but seeded from it on first run so
+ * existing web users don't register as brand-new installs) and capture a deferred deep-link `scalebun_click_id`
+ * from the landing URL (persist + scrub it from the address bar → privacy + no re-capture on share/refresh).
+ * The backend attribution engine already consumes `installation_id` + `identifiers.click_id`.
+ */
+function resolveAttribution(deviceId) {
+    let installationId = '';
+    let clickId;
+    try {
+        if (typeof localStorage !== 'undefined') {
+            installationId = localStorage.getItem(K_INSTALL) ?? '';
+            if (!installationId) {
+                installationId = deviceId || `web_${uuid()}`; // seed from the existing device id → no phantom install
+                localStorage.setItem(K_INSTALL, installationId);
+            }
+            clickId = localStorage.getItem(K_CLICK) ?? undefined;
+        }
+    }
+    catch {
+        /* storage disabled */
+    }
+    if (!installationId)
+        installationId = deviceId || `web_${uuid()}`; // never empty (server requires it)
+    try {
+        if (typeof location !== 'undefined' && location.search) {
+            const url = new URL(location.href);
+            const c = url.searchParams.get('scalebun_click_id');
+            if (c && CLICK_RE.test(c)) {
+                clickId = c;
+                try {
+                    if (typeof localStorage !== 'undefined')
+                        localStorage.setItem(K_CLICK, c);
+                }
+                catch {
+                    /* storage disabled — click still rides this session's events */
+                }
+                url.searchParams.delete('scalebun_click_id');
+                try {
+                    history.replaceState(history.state, '', url.pathname + url.search + url.hash);
+                }
+                catch {
+                    /* history unavailable — leave the URL as-is */
+                }
+            }
+        }
+    }
+    catch {
+        /* malformed URL */
+    }
+    return clickId ? { installationId, clickId } : { installationId };
+}
+function loadAnonId(cookieDomain) {
+    // Cross-subdomain: the shared cookie is the source of truth so every sub-domain resolves to one id.
+    if (cookieDomain) {
+        const c = readCookie(K_ANON);
+        if (c) {
+            try {
+                if (typeof localStorage !== 'undefined')
+                    localStorage.setItem(K_ANON, c);
+            }
+            catch {
+                /* storage disabled */
+            }
+            return c;
+        }
+    }
+    try {
+        if (typeof localStorage !== 'undefined') {
+            const existing = localStorage.getItem(K_ANON);
+            const id = existing ?? newAnonId();
+            if (!existing)
+                localStorage.setItem(K_ANON, id);
+            if (cookieDomain)
+                writeCookie(K_ANON, id, cookieDomain);
+            return id;
+        }
+    }
+    catch {
+        /* storage disabled */
+    }
+    const id = newAnonId();
+    if (cookieDomain)
+        writeCookie(K_ANON, id, cookieDomain);
+    return id;
+}
+export class AnalyticsFeature {
+    constructor() {
+        this.name = 'analytics';
+        this.ctx = null;
+        this.active = false;
+        this.clientKey = '';
+        this.apiBaseUrl = '';
+        this.deviceId = '';
+        this.installationId = ''; // W1b — stable install id (seeded from deviceId; distinct thereafter)
+        this.attributionProps = {}; // W6.0 — first-touch web acquisition, merged into every event
+        this.anonymousId = '';
+        this.userId = loadUid();
+        this.superProps = {}; // A1 — merged into every event's properties
+        this.groups = {}; // A1 — B2B group memberships stamped on every event
+        this.queue = [];
+        this.buffer = new PersistentBuffer(IDB_KEY);
+        this.persisted = false; // whether IDB currently holds a non-empty snapshot (avoids redundant writes)
+        this.backoff = new Backoff();
+        this.sampleRate = 1; // A6 — per-user analytics sampling (1 = keep all)
+        this.droppedCount = 0;
+        this.sampledOutCount = 0; // A7 — events thinned by per-user sampling
+        this.flushCount = 0; // A7 — successful /batch sends
+    }
+    /** Egress telemetry (Dev Panel / debug): events waiting to send + events dropped (invalid input,
+     *  queue overflow, or stale-on-reload). */
+    get pending() {
+        return this.queue.length;
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    /** A7 — analytics-lane observability (parity with perfStats/egressStats). */
+    get stats() {
+        return {
+            pending: this.queue.length,
+            dropped: this.droppedCount,
+            sampledOut: this.sampledOutCount,
+            flushes: this.flushCount,
+            sampleRate: this.sampleRate,
+        };
+    }
+    get isActive() {
+        return this.active;
+    }
+    setup(ctx) {
+        this.ctx = ctx;
+        this.clientKey = ctx.clientKey ?? '';
+        this.apiBaseUrl = ctx.apiBaseUrl ?? '';
+        this.deviceId = ctx.deviceId ?? '';
+        // W1b — resolve the stable install id + capture a deferred deep-link click token BEFORE any event is
+        // built, so every event carries a consistent installation_id (no split-install race).
+        const attr = resolveAttribution(this.deviceId);
+        this.installationId = attr.installationId;
+        this.clickId = attr.clickId;
+        const attrib = captureWebAttribution(); // W6.0 — first-touch referrer/utm/landing
+        this.attributionProps = attrib.props;
+        this.cookieDomain = ctx.analyticsOptions?.cookieDomain; // A6
+        this.anonymousId = loadAnonId(this.cookieDomain);
+        this.superProps = loadJson(K_SUPER);
+        this.groups = loadJson(K_GROUPS);
+        this.plan = ctx.analyticsOptions?.plan; // A3
+        const sr = ctx.analyticsOptions?.sampleRate; // A6
+        if (typeof sr === 'number' && sr >= 0 && sr <= 1)
+            this.sampleRate = sr;
+        if (!this.clientKey || !this.apiBaseUrl)
+            return;
+        // W6.1 — record the acquisition touchpoint once (server classifies the channel). After the identity
+        // is resolved so the touchpoint stitches to the right session/subject.
+        if (attrib.isNew)
+            void this.recordTouchpoint();
+        this.timer = setInterval(() => this.autoFlush(), FLUSH_MS);
+        if (typeof window !== 'undefined') {
+            // On page close: snapshot the queue to IDB FIRST (survives if the keepalive send dies mid-flight),
+            // then keepalive-flush. A successful send clears the snapshot; a reload re-sends (server dedups).
+            this.onHide = () => {
+                void this.persist();
+                void this.flush(true);
+            };
+            window.addEventListener('pagehide', this.onHide);
+        }
+        // On reconnect: clear the backoff window and flush immediately (don't wait for the next tick).
+        this.offOnline = onOnline(() => {
+            this.backoff.reset();
+            this.autoFlush();
+        });
+        this.active = true;
+        // W1b — emit `first_open` exactly once per install (RN parity) → triggers the backend attribution
+        // matcher (click_id → deterministic install attribution). Idempotent server-side too.
+        this.maybeFirstOpen();
+        // A2 — promote friction (rage/dead click) from the capture-signal bus to first-class product
+        // events, so frustration funnels ("who rage-clicked before churning") work with zero setup.
+        this.offSignal = ctx.onSignal?.((reason, detail) => {
+            if (!this.active)
+                return;
+            if (reason === 'rage')
+                this.track('$rageclick');
+            else if (reason === 'dead')
+                this.track('$deadclick');
+            else if (reason === 'shake')
+                this.track('$shake'); // W5.1 — implicit frustration signal
+            // Errors → a product event, so "users who hit an error" is a cohort and a funnel step rather
+            // than something only visible in the errors lane. The errors lane still owns the full report
+            // (stack, frames, causes); this is the aggregate-analytics shadow of it, keyed by fingerprint
+            // so the two can be joined.
+            else if (reason === 'error')
+                this.track('$exception', detail);
+            // Vitals were performance-lane-only, so "conversion for sessions whose LCP was poor" could not be
+            // asked. The rating travels with the value so a funnel filter means the same thing the dashboard
+            // colouring does.
+            else if (reason === 'web_vital')
+                this.track('$web_vital', detail);
+            /**
+             * Exit intent was session-lane-only, which meant it was captured and unreadable at the same time.
+             *
+             * ExitIntentFeature calls `ctx.trackEvent`, and that writes to the SESSION lane — the right place
+             * for the replay timeline, the wrong place for aggregation. Every read that asks "which routes do
+             * people try to leave" comes off the analytics lane, so the exit-intent dashboard reported zero
+             * while 125 genuine detections sat in the session lane across 8 days. Promoting it here is the
+             * same move already made for errors and vitals, and it makes exit intent a funnel step and a
+             * cohort ("visitors who tried to leave the pricing page") rather than a replay-only curiosity.
+             */
+            else if (reason === 'exit_intent')
+                this.track('$exit_intent', detail);
+        });
+        // Drain anything persisted from a previous load (offline/crash before flush) → at-least-once,
+        // dropping events older than the max age so a reload doesn't replay stale analytics.
+        void this.buffer.load().then((prev) => {
+            const arr = Array.isArray(prev) ? prev : [];
+            const fresh = freshOnly(arr, (e) => e.event_time, now());
+            this.droppedCount += arr.length - fresh.length; // stale events dropped on drain
+            if (this.active && fresh.length) {
+                this.queue.unshift(...fresh);
+                this.trim();
+                this.persisted = true;
+                this.autoFlush();
+            }
+            else if (fresh.length < arr.length) {
+                void this.buffer.clear(); // snapshot held only stale events → purge it
+            }
+        });
+        // Autocapture (default on) → $autocapture/$submit/$pageview straight onto the analytics lane.
+        // Lazy-loaded (event-driven, not latency-critical) so it stays out of the core bundle.
+        if (ctx.autocapture !== false) {
+            void import('./autocapture.js')
+                .then(({ installAutocapture }) => {
+                if (this.active) {
+                    this.stopAutocapture = installAutocapture({
+                        // `capture_source: 'automatic'` marks zero-instrumentation capture, matching the RN
+                        // bus's compactProperties(). The backend event catalog files a definition's `source`
+                        // off this field, so without it every autocaptured web event was recorded as
+                        // hand-instrumented `sdk` while the identical mobile event was `automatic`.
+                        // Stamped here (one site) rather than in each of autocapture's emit points.
+                        onEvent: (e) => this.track(e.name, { ...e.props, capture_source: 'automatic' }),
+                        // Opt-in label masking (`privacy.maskEventText`); off by default.
+                        maskText: ctx.maskEventText === true,
+                    });
+                }
+            })
+                .catch(() => {
+                /* chunk load failed — analytics lane still works without autocapture */
+            });
+        }
+    }
+    get usable() {
+        return this.active && !!this.clientKey && !!this.apiBaseUrl && typeof fetch !== 'undefined';
+    }
+    get sessionId() {
+        return this.ctx?.sessionId;
+    }
+    /** W6.1 — record the acquisition touchpoint once (fire-and-forget). The backend classifies the channel
+     *  from these signals (org rules), stitches to the session/subject, and lights up the Traffic Sources
+     *  report. Fail-soft: the same signals also ride Event.properties, so nothing is lost if this drops. */
+    async recordTouchpoint() {
+        if (!this.clientKey || !this.apiBaseUrl || typeof fetch === 'undefined')
+            return;
+        const p = this.attributionProps;
+        try {
+            await fetch(`${this.apiBaseUrl}/ingestion/attribution`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-scalebun-client-key': this.clientKey },
+                keepalive: true,
+                body: JSON.stringify({
+                    sessionId: this.sessionId,
+                    anonymousId: this.anonymousId || undefined,
+                    source: p.utm_source,
+                    medium: p.utm_medium,
+                    campaign: p.utm_campaign,
+                    content: p.utm_content,
+                    term: p.utm_term,
+                    landingUrl: p.landing_url,
+                    referrer: p.referrer,
+                    referrerDomain: p.referrer_domain,
+                    clickToken: this.clickId,
+                }),
+            });
+        }
+        catch {
+            /* fail-soft — Event.properties still carries the same attribution */
+        }
+    }
+    /** W1b — emit `first_open` once per install. Guarded by localStorage; if storage is unavailable it may
+     *  re-emit across loads, which the backend once-guard (Installation.firstOpenAt) absorbs. */
+    maybeFirstOpen() {
+        let done = false;
+        try {
+            done = typeof localStorage !== 'undefined' && localStorage.getItem(K_FIRSTOPEN) === '1';
+        }
+        catch {
+            /* storage disabled */
+        }
+        if (done)
+            return;
+        try {
+            if (typeof localStorage !== 'undefined')
+                localStorage.setItem(K_FIRSTOPEN, '1');
+        }
+        catch {
+            /* storage disabled */
+        }
+        this.track('first_open');
+    }
+    /** W1b — the current install id (for the host / attribution API). */
+    getInstallationId() {
+        return this.installationId;
+    }
+    /** W1b — set the deferred deep-link attribution token manually (for hosts running their own redirect).
+     *  Rides `identifiers.click_id` on every subsequent event; the backend matches it to a Click row. */
+    setClickId(id) {
+        if (!id || !CLICK_RE.test(id))
+            return;
+        this.clickId = id;
+        try {
+            if (typeof localStorage !== 'undefined')
+                localStorage.setItem(K_CLICK, id);
+        }
+        catch {
+            /* storage disabled */
+        }
+    }
+    build(name, props) {
+        const replay = getReplayCoord(); // A0 — deep-link the event to the live replay frame
+        // A1 — super-properties merge under explicit props (call-site props always win). W6.0 — first-touch
+        // web attribution (referrer/utm/landing) sits at the lowest precedence, so it rides every event but
+        // never clobbers a super-prop or a call-site prop of the same key.
+        const base = Object.keys(this.attributionProps).length ? { ...this.attributionProps, ...this.superProps } : this.superProps;
+        const merged = Object.keys(base).length ? { ...base, ...props } : props;
+        // A3 — PII scrub every event's props (emails/secrets/cards) + normalize the event name.
+        const cleaned = merged && Object.keys(merged).length ? scrubProps(merged) : undefined;
+        const hasGroups = Object.keys(this.groups).length > 0;
+        return {
+            event_id: uuid(),
+            event_name: name.trim(),
+            event_time: now(),
+            platform: 'web',
+            installation_id: this.installationId,
+            ...(this.deviceId ? { device_id: this.deviceId } : {}),
+            anonymous_id: this.anonymousId,
+            ...(this.sessionId ? { session_id: this.sessionId } : {}),
+            ...(this.userId ? { user_id: this.userId } : {}),
+            ...(this.clickId ? { identifiers: { click_id: this.clickId } } : {}),
+            ...(cleaned ? { properties: cleaned } : {}),
+            ...(hasGroups ? { groups: { ...this.groups } } : {}),
+            ...(replay ? { replay } : {}),
+            context: { sdk_version: SDK_VERSION },
+        };
+    }
+    /** A0/A1 — the current analytics identity + global context, shared with the session lane so both
+     *  transports stamp the same anon/user id, super-properties and groups onto every event. */
+    get identity() {
+        return {
+            anonymousId: this.anonymousId,
+            userId: this.userId,
+            groups: this.groups,
+            superProps: this.superProps,
+        };
+    }
+    /** A3 — evaluate a user event against the tracking plan (if configured). Warns on violations and
+     *  returns whether to DROP it (strict mode). The facade calls this once to gate BOTH lanes. */
+    evaluate(name, props) {
+        if (!this.plan)
+            return { drop: false };
+        const v = evaluateEvent(this.plan, name, props);
+        if (v.warnings.length) {
+            try {
+                for (const w of v.warnings)
+                    console.warn(`[scalebun] tracking-plan: ${w}`);
+            }
+            catch {
+                /* console unavailable */
+            }
+        }
+        return { drop: v.drop };
+    }
+    /** A1 — register global "super" properties merged into every subsequent event (persisted). */
+    register(props) {
+        if (!props || typeof props !== 'object')
+            return;
+        this.superProps = { ...this.superProps, ...props };
+        saveJson(K_SUPER, this.superProps);
+    }
+    /** A1 — remove a previously-registered super-property. */
+    unregister(key) {
+        if (!(key in this.superProps))
+            return;
+        const { [key]: _drop, ...rest } = this.superProps;
+        this.superProps = rest;
+        saveJson(K_SUPER, this.superProps);
+    }
+    /** A1 — associate the user with a B2B group; stamps `groups` on every event + emits one `$group`
+     *  carrying the group traits (server upserts the group profile, like `$identify` for users). */
+    group(groupType, groupKey, traits) {
+        if (!groupType || !groupKey)
+            return;
+        this.groups = { ...this.groups, [groupType]: groupKey };
+        saveJson(K_GROUPS, this.groups);
+        if (this.usable) {
+            this.enqueue(this.build('$group', { group_type: groupType, group_key: groupKey, ...(traits ?? {}) }));
+        }
+    }
+    /** A1 — link the current identity to a prior id (anon→known or cross-device). Sets user_id + emits
+     *  an `$alias` carrying the previous id so the backend graph links them deterministically. */
+    alias(newUserId, previousId) {
+        if (!newUserId)
+            return;
+        const prev = previousId ?? this.userId ?? this.anonymousId;
+        this.userId = newUserId;
+        saveUid(newUserId);
+        if (this.usable)
+            this.enqueue(this.build('$alias', { previous_id: prev }));
+    }
+    /** A1 — logout: mint a fresh anonymous id and clear user/super-props/groups so the next user's
+     *  events aren't attributed to the previous one. */
+    reset() {
+        this.userId = undefined;
+        saveUid(undefined);
+        this.anonymousId = newAnonId();
+        try {
+            if (typeof localStorage !== 'undefined')
+                localStorage.setItem(K_ANON, this.anonymousId);
+        }
+        catch {
+            /* storage disabled */
+        }
+        if (this.cookieDomain)
+            writeCookie(K_ANON, this.anonymousId, this.cookieDomain); // A6 — keep the shared cookie in sync
+        this.superProps = {};
+        this.groups = {};
+        saveJson(K_SUPER, this.superProps);
+        saveJson(K_GROUPS, this.groups);
+    }
+    track(name, props) {
+        if (!this.usable || !name)
+            return;
+        if (!keepEvent(name, this.anonymousId, this.sampleRate)) {
+            this.sampledOutCount++; // A6/A7 — thinned by per-user sampling
+            return;
+        }
+        this.enqueue(this.build(name, props));
+    }
+    /** A4 — revenue event (one-time / subscription / refund). revenue/currency top-level (normalized),
+     *  revenue_type + LTV fields (product/quantity/recurrence) in properties; server-deduped by
+     *  transaction_id. Group attribution is automatic via the stamped `groups`. */
+    trackPurchase(norm) {
+        if (!this.usable)
+            return;
+        const env = this.build('purchase', norm.props);
+        env.revenue = norm.revenue;
+        env.currency = norm.currency;
+        this.enqueue(env);
+    }
+    /** W2 — record a subscription lifecycle change. Emits a `$subscription` event whose properties carry
+     *  the subscription payload (+ the replay coord, so the backend ledger can deep-link the session of the
+     *  change). Validate-or-drop, like trackPurchase. */
+    trackSubscription(input) {
+        if (!this.usable)
+            return;
+        this.pendingSubscription = (this.pendingSubscription ?? Promise.resolve()).then(async () => {
+            try {
+                const { normalizeSubscription } = await import('./subscription.js');
+                const props = normalizeSubscription(input);
+                if (!props) {
+                    this.droppedCount++;
+                    return;
+                }
+                if (!this.usable)
+                    return;
+                const replay = getReplayCoord();
+                this.enqueue(this.build('$subscription', replay ? { ...props, replay } : props));
+            }
+            catch {
+                /* optional analytics chunk unavailable — preserve the host app's no-throw contract */
+            }
+        });
+    }
+    /** Stamp user_id onto subsequent events + emit one $identify so the backend links the profile now. */
+    identify(userId, traits) {
+        if (!userId)
+            return;
+        this.userId = userId;
+        saveUid(userId);
+        if (this.usable)
+            this.enqueue(this.build('$identify', traits));
+    }
+    enqueue(env) {
+        this.queue.push(env);
+        this.trim();
+        if (this.queue.length >= BATCH_MAX)
+            this.autoFlush();
+    }
+    /** Bound the in-memory queue to QUEUE_CAP, counting the oldest dropped events for telemetry. */
+    trim() {
+        const over = this.queue.length - QUEUE_CAP;
+        if (over > 0) {
+            this.queue.splice(0, over);
+            this.droppedCount += over;
+        }
+    }
+    /** Timer/threshold/reconnect-driven flush: skip while offline or inside the backoff window so a
+     *  struggling/offline server isn't hit every tick. Explicit flush()/keepalive sends bypass this. */
+    autoFlush() {
+        if (!isOnline() || !this.backoff.ready(now()))
+            return;
+        void this.flush();
+    }
+    async flush(keepalive = false) {
+        await this.pendingSubscription;
+        if (!this.usable || !this.queue.length)
+            return;
+        const batch = this.queue.splice(0, this.queue.length);
+        // W1a — HMAC-sign the EXACT body bytes for tamper-evident ingestion (byte-identical to RN + the
+        // backend verify). Lazy signer; fail-open → an unsigned batch is accepted as an old SDK (no penalty).
+        // The batch is already mirrored to IDB below, so a page that dies mid-sign re-sends it (signed) next
+        // load — delivery is never blocked on signing.
+        const body = JSON.stringify({ events: batch });
+        try {
+            const { signatureHeaders } = await import('../../transport/sign.js');
+            const sig = await signatureHeaders(this.clientKey, body);
+            const res = await fetch(`${this.apiBaseUrl}/batch`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-scalebun-client-key': this.clientKey, ...sig },
+                body,
+                keepalive,
+            });
+            if (res.ok) {
+                this.backoff.reset();
+                this.flushCount++; // A7
+            }
+            else {
+                this.backoff.fail(now()); // transient server error → widen the retry window
+                this.requeue(batch);
+            }
+        }
+        catch {
+            this.backoff.fail(now()); // offline / network error → back off + keep for retry
+            this.requeue(batch);
+        }
+        // Mirror the (now drained or requeued) queue to IDB: persist leftovers, clear on full success.
+        void this.persist();
+    }
+    requeue(batch) {
+        this.queue.unshift(...batch);
+        this.trim();
+    }
+    /** Keep the IDB snapshot in sync with the in-memory queue. Writes only when state changes:
+     *  saves a non-empty queue (so it survives reload/crash), clears once everything has flushed. */
+    async persist() {
+        if (this.queue.length) {
+            this.persisted = true;
+            await this.buffer.save(capBytes(this.queue)); // bound persisted bytes (drops oldest if over)
+        }
+        else if (this.persisted) {
+            this.persisted = false;
+            await this.buffer.clear();
+        }
+    }
+    teardown() {
+        this.stopAutocapture?.();
+        this.stopAutocapture = undefined;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        if (this.onHide && typeof window !== 'undefined')
+            window.removeEventListener('pagehide', this.onHide);
+        this.onHide = undefined;
+        this.offOnline?.();
+        this.offSignal?.();
+        this.offSignal = undefined;
+        this.offOnline = undefined;
+        // Consent-revoke path (bootstrap teardownAll) → DROP unsent analytics (privacy). Normal page
+        // close already flushed via pagehide. teardown() is an EXPLICIT shutdown (close()/consent-deny),
+        // so purge the persisted snapshot too — a reload/crash never calls teardown, so durability holds
+        // there (the data-loss case we close); only an intentional teardown discards.
+        this.queue = [];
+        this.persisted = false;
+        void this.buffer.clear();
+        this.active = false;
+    }
+}
+//# sourceMappingURL=AnalyticsFeature.js.map