@scalebun/web 1.0.0

package/dist/public/ScaleBunFacade.js

@@ -0,0 +1,787 @@
+/**
+ * ScaleBunFacade — the public singleton. Methods are crash-safe: the SDK never throws into the host
+ * app. Everything funnels into the ONE pipeline as contract Items.
+ */
+import { SDKBootstrapper } from '../bootstrap/SDKBootstrapper';
+import { buildBugReportPayload } from '../features/bugreport/collect';
+import { now, uuid, addBreadcrumb as addCrumb, getReplayCoord, scrubProps, patchEvalContext, clearEvalContext, isServer, getRuntime, setNonce } from '../core';
+import { normalizeRevenue } from '../features/analytics/revenue';
+import { setTag, setContext, setErrorLevel } from '../features/errors/scope';
+import { NOOP_TXN } from '../features/performance/trace/types';
+class ScaleBunFacade {
+    constructor() {
+        this.rt = null;
+        this.ready = false;
+        /** A setConsent(...) call made before init() — applied once the runtime exists. */
+        this.pendingConsent = null;
+        /** E4 — Web Push: lazy-loaded on the first enablePush()/onNotificationOpened() call. */
+        this.pushFeature = null;
+        this.coachFeature = null;
+        this.coachController = null;
+        /** onNotificationOpened callbacks registered before the push module loads. */
+        this.pendingPushOpenCbs = [];
+        this.settle = null;
+        this.settled = new Promise((r) => { this.settle = r; });
+        // ── Namespaced sub-APIs (parity with the RN facade) ──────────────────────────
+        this.replay = {
+            /** Live diagnostics — mode/sample bucket, adaptive quality level, segments, dropped/shed counts.
+             *  null when replay isn't recording (off, or a non-sampled session). */
+            stats: () => this.replayFeature()?.stats() ?? null,
+            /** Force a re-keyframe so the player gets a clean seek point before a risky flow. */
+            checkpoint: (reason) => this.replayFeature()?.checkpoint(reason),
+            /** Promote the buffered pre-roll → live capture now (e.g. the user clicked "report a problem"). */
+            flush: () => this.replayFeature()?.flush(),
+            /** Stop recording for this session. */
+            stop: () => this.replayFeature()?.teardown(),
+            /** Resume capture after pause() (re-keyframes the current DOM). Alias of resume(). */
+            start: () => this.replayFeature()?.resume(),
+            /** Pause capture without ending the session — the buffered pre-roll is kept. */
+            pause: () => this.replayFeature()?.pause(),
+            /** Resume capture after pause(). */
+            resume: () => this.replayFeature()?.resume(),
+            /** Change replay text-masking at runtime, e.g. mask on a sensitive screen: `setPrivacy({ maskAllText: true })`. */
+            setPrivacy: (policy) => this.replayFeature()?.setPrivacy(policy),
+        };
+        this.performance = {
+            /**
+             * Open a RUM transaction (a timed root with a bounded span tree). Returns a handle:
+             * `const t = ScaleBun.performance.startTransaction('checkout'); const s = t.startSpan('validate');
+             * s.finish(); t.finish();`. Safe before the engine loads (no-op handle).
+             */
+            startTransaction: (name) => {
+                const perf = this.rt?.registry.get('performance');
+                return perf?.startTransaction?.(name) ?? NOOP_TXN;
+            },
+            /** Begin a custom trace span — routed through PerformanceFeature (F-PERF). */
+            startTrace: (name) => {
+                const perf = this.rt?.registry.get('performance');
+                perf?.startTrace?.(name);
+            },
+            /** End a custom trace span → emits a `performance` item with the elapsed time. */
+            stopTrace: (name) => {
+                const perf = this.rt?.registry.get('performance');
+                perf?.stopTrace?.(name);
+            },
+            markScreenLoadStart: (_screen) => { },
+            sendMetric: (metric, value) => {
+                this.rt?.pipeline.emit({ kind: 'performance', metric, value, timestamp: now() });
+            },
+        };
+        this.session = {
+            start: () => { },
+            end: () => {
+                void this.close();
+            },
+            emitEvent: (name, props) => {
+                this.track(name, props);
+            },
+        };
+        this.engage = {
+            /** Track a custom event that can trigger a survey (alias of `track`, kept for parity). */
+            track: (name, props) => this.track(name, props),
+            /** Re-fetch the active survey config (e.g. after login / a context change). */
+            refresh: () => this.engageFeature()?.refresh() ?? Promise.resolve(),
+            /** E2 — submit a response from a custom survey UI → 'success'|'error' (retried, idempotent). */
+            submit: (surveyId, result) => this.engageFeature()?.submit(surveyId, result) ?? Promise.resolve('error'),
+            /** E2 — emit one rating-funnel event (eligible/shown/dismissed/selected/store_redirect). */
+            emitRatingEvent: (type, input) => this.engageFeature()?.emitRatingEvent(type, input),
+            /** E2 — dev/QA: clear on-device engage state so campaigns show again (no incognito needed). */
+            resetInAppState: () => this.engageFeature()?.resetInAppState() ?? Promise.resolve(),
+        };
+        this.push = {
+            /** Subscribe to Web Push (alias of enablePush) — call from a user gesture. */
+            enable: (opts) => this.enablePush(opts),
+            /**
+             * Opt out of Web Push: unsubscribes this browser and revokes the token server-side immediately
+             * (pass `{ revokeServerSide: false }` to skip the server call). The device row itself is kept —
+             * it carries this device's analytics/replay identity, not just its push token.
+             */
+            disable: (opts) => this.ensurePush().then((p) => p?.disable(opts) ?? false),
+            /** Current push status (supported / permission / subscribed / endpoint / actionable state). */
+            status: () => this.ensurePush().then((p) => p?.status() ??
+                // The push feature could not even load — that is a browser incapable of push, not a person
+                // who refused, so it reports `unsupported` rather than falling back to a permission value.
+                Promise.resolve({
+                    supported: false,
+                    permission: 'default',
+                    subscribed: false,
+                    endpoint: null,
+                    state: 'unsupported',
+                })),
+            /** The current browser PushSubscription JSON, or null. */
+            getSubscription: () => this.ensurePush().then((p) => p?.getSubscription() ?? null),
+            /**
+             * P1 — diagnose the whole push path and say what to fix. Safe to call anywhere: it never prompts
+             * for permission and never throws. Returns { ok, blocking, checks[] } where each check carries its
+             * own label + fix text, so a settings screen can render the report generically.
+             */
+            check: async (opts) => {
+                const p = await this.ensurePush();
+                if (p)
+                    return p.check(opts);
+                // Not initialized — the explanatory report lives in the lazy chunk, not in eager core.
+                return (await import('../features/push/diagnostics')).notInitializedReport();
+            },
+        };
+        // ── Install attribution (W1b) — MMP primitives on the analytics lane ────────────
+        this.attribution = {
+            /** The stable install id (seeded from the device id on first run). */
+            getInstallationId: () => this.analyticsFeature()?.getInstallationId() ?? '',
+            /** Set the deferred deep-link attribution token (auto-captured from `?scalebun_click_id=` at init; this is
+             *  for hosts running their own redirect). Rides every subsequent event → deterministic attribution. */
+            setClickId: (id) => this.analyticsFeature()?.setClickId(id),
+        };
+        /** A5 — flag/experiment exposures already recorded this session (dedup key `flag=value`). */
+        this.flagExposed = new Set();
+        /**
+         * Feature flags:
+         *  - `scalebun.flags.isEnabled('new-checkout')` — boolean gate.
+         *  - `scalebun.flags.variation('cta-color', '#000')` — F2 multivariate served value (typed).
+         *  - `scalebun.flags.variationDetail('cta-color', '#000')` — F2 `{ value, variant, reason }` (LD-style).
+         * Each read records one exposure (variant name when multivariate, else the boolean).
+         */
+        this.flags = {
+            isEnabled: (key) => {
+                const c = this.cfg();
+                const v = c?.isEnabled(key) ?? false;
+                // Only record when the answer came from real config. Exposing an unknown flag writes a `false`
+                // the user never experienced — and because the dedupe key includes the value, the real value
+                // then emits a SECOND, contradictory exposure for the same person.
+                if (c?.knows(key))
+                    this.recordExposure(key, v);
+                return v;
+            },
+            variation: (key, fallback) => this.flags.variationDetail(key, fallback).value,
+            variationDetail: (key, fallback) => {
+                const d = this.cfg()?.variationDetail(key, fallback) ?? { value: fallback, variant: null, reason: 'FLAG_NOT_FOUND' };
+                // Exposure token: the variant name when known, else a primitive value (objects aren't exposure keys).
+                const token = d.variant ?? (typeof d.value === 'object' ? null : d.value);
+                this.recordExposure(key, typeof token === 'number' ? String(token) : token, d.reason); // F6 — stamp reason
+                return d;
+            },
+            // F3 — readiness + live updates. `ready()` resolves once the first fetch settles (flags are usable
+            // synchronously before that via bootstrap/cache); `onChange` fires when a new config version applies.
+            ready: () => this.cfg()?.ready() ?? Promise.resolve(),
+            onChange: (cb) => this.cfg()?.onChange(cb) ?? (() => { }),
+            // F3 — QA overrides: force a flag/experiment/rollout locally (persisted) for testing.
+            override: (key, value) => this.cfg()?.override(key, value),
+            clearOverride: (key) => this.cfg()?.clearOverride(key),
+            clearOverrides: () => this.cfg()?.clearOverrides(),
+        };
+        /** Remote config: `scalebun.config.get('max_items', 10)` · `scalebun.config.refresh()`. */
+        this.config = {
+            get: (key, fallback) => this.cfg()?.get(key, fallback) ?? fallback,
+            refresh: () => this.cfg()?.refresh() ?? Promise.resolve(),
+        };
+        /** Feature rollouts / kill-switches: `scalebun.rollouts.isOn('beta-banner')`. */
+        this.rollouts = {
+            isOn: (key) => {
+                const v = this.cfg()?.isOn(key) ?? false;
+                this.recordExposure(key, v);
+                return v;
+            },
+        };
+        /** Experiments: `scalebun.experiments.variant('pricing-test')` → variant key (logs exposure once). */
+        this.experiments = {
+            variant: (key) => {
+                const v = this.cfg()?.variant(key) ?? null;
+                this.recordExposure(key, v);
+                return v;
+            },
+        };
+        /** `scalebun.profiler.start()` … `await scalebun.profiler.stop()` around a slow operation. */
+        this.profiler = {
+            available: () => this.prof()?.available() ?? false,
+            start: (sampleIntervalMs) => this.prof()?.start(sampleIntervalMs) ?? false,
+            stop: () => this.prof()?.stop() ?? Promise.resolve(false),
+        };
+        // ── Watchdog (F-WDOG, W5.2) — continuous resource health + local incidents (opt-in) ─
+        /** `scalebun.watchdog.stats()` — incidents/drops/rollups + which enrichment tiers are live. */
+        this.watchdog = {
+            stats: () => {
+                const w = this.rt?.registry.get('watchdog');
+                return w?.stats?.() ?? null;
+            },
+        };
+    }
+    /**
+     * Resolves once `init()` has SETTLED — succeeded or failed. Await it before reaching for a feature
+     * controller from component code.
+     *
+     * ⚠️ Why this exists: accessors like `inbox()` return a NO-OP object when the runtime is not built
+     * yet, and every method on it silently does nothing. In a component tree that is the NORMAL case,
+     * not an edge case — React runs child effects BEFORE parent effects, so a navbar bell's effect
+     * fires before the root layout's `init()` has even been called, let alone awaited. The host then
+     * holds a dead controller forever and sees no error: `mount()` just does nothing.
+     *
+     * ⚠️ Settled, not succeeded. If init failed there is genuinely no SDK, and the no-op accessors are
+     * the honest answer — but the host must not hang waiting for a promise that will never resolve.
+     */
+    whenReady() {
+        return this.settled;
+    }
+    /** Initialize the SDK. Builds config → pipeline → features → starts capture. */
+    async init(config) {
+        if (this.ready)
+            return;
+        // CSP: stash the nonce before anything injects DOM. Cheap + runtime-agnostic (no-op on SSR/edge,
+        // where nothing is injected). An explicit config nonce wins over the loader's auto-detected one.
+        setNonce(config?.csp?.nonce);
+        if (isServer()) {
+            const rt = getRuntime();
+            if (rt === 'edge' || rt === 'worker') {
+                // Edge / worker LITE lane: no DOM, no session/replay, no persistence — analytics + config send
+                // via fetch (transport-only, ephemeral identity). These runtimes handle a request and do NOT
+                // hydrate on a client, so server-side capture is the ONLY capture (unlike SSR-node below).
+                try {
+                    this.rt = await SDKBootstrapper.bootstrap(config, { edge: true });
+                    this.ready = true;
+                }
+                catch (e) {
+                    if (typeof console !== 'undefined')
+                        console.warn('[scalebun] edge init failed:', e);
+                }
+                return;
+            }
+            // SSR-node / unknown: deterministic no-op — capture activates on the CLIENT after hydration, where
+            // the app's client bootstrap calls init() again in the browser. Zero-cost early return (no network,
+            // no observers, no storage). Every framework adapter inherits this guard.
+            if (config?.debug && typeof console !== 'undefined') {
+                console.warn('[scalebun] init() on SSR — deferring capture to the client.');
+            }
+            return;
+        }
+        try {
+            this.rt = await SDKBootstrapper.bootstrap(config);
+            this.ready = true;
+            // Apply a consent decision made before init resolved.
+            if (this.pendingConsent !== null) {
+                this.rt.setConsent(this.pendingConsent);
+                this.pendingConsent = null;
+            }
+            // Wire the bug-report widget: give the feature the full submit path + mount the launcher.
+            if (this.rt.config.features.bugReport !== false) {
+                const bug = this.rt.registry.get('bugReport');
+                bug?.setSubmit?.((i) => this.reportBug(i));
+                if (this.rt.config.bugReport.launcher) {
+                    void bug?.mountLauncher?.({
+                        position: this.rt.config.bugReport.position,
+                        label: this.rt.config.bugReport.label,
+                    });
+                }
+            }
+            /**
+             * Push soft-ask — opt-in, and lazily loaded so it costs a tenant that does not use it NOTHING.
+             *
+             * This is the whole reason a host no longer has to write
+             * `document.body.addEventListener('click', () => push.enable())` themselves: browsers only
+             * allow the permission prompt from a real user gesture, so SOMETHING has to be clicked. Making
+             * that something ours means it can be configured instead of coded — and it lets us ask
+             * reversibly first, which is the part that actually protects the tenant's accept rate.
+             *
+             * ⚠️ The dynamic import is what keeps core under its gate; do not hoist it to a static import.
+             */
+            const softAsk = config?.push?.softAsk;
+            if (softAsk) {
+                void import('../features/push/softAsk')
+                    .then(({ armSoftAsk }) => armSoftAsk(softAsk, {
+                    enable: () => this.enablePush(),
+                    permission: () => Notification.permission,
+                }))
+                    // Never take down init for an optional prompt.
+                    .catch(() => undefined);
+            }
+        }
+        catch (e) {
+            // Never take down the host app.
+            if (typeof console !== 'undefined')
+                console.warn('[scalebun] init failed:', e);
+        }
+        finally {
+            // `finally`, not the success branch: a host awaiting whenReady() must never hang because init
+            // threw. A failed init means the no-op accessors are the truth, which is still an answer.
+            this.settle?.();
+        }
+    }
+    /**
+     * Resolve consent-mode (GDPR/CIPA) — call from your CMP's grant/deny callback. With
+     * `requireConsent:true`, the SDK captures + sends nothing until `setConsent(true)`. Safe to call
+     * before init() (the decision is stashed and applied once ready).
+     */
+    setConsent(granted) {
+        if (this.rt)
+            this.rt.setConsent(granted);
+        else
+            this.pendingConsent = granted;
+    }
+    /** Track a custom event. Fans out to the replay/session lane (correlation) AND the product-analytics
+     *  lane (Event → funnels/events dashboards), and feeds Engage `custom_event` triggers. */
+    track(name, props) {
+        // A3 — a strict tracking-plan violation drops the event from BOTH lanes (one decision here).
+        if (this.analyticsFeature()?.evaluate(name, props).drop)
+            return;
+        this.rt?.pipeline.emit(this.enrichEvent({ kind: 'event', name, props, timestamp: now() }));
+        this.analyticsFeature()?.track(name, props);
+        this.engageFeature()?.onCustomEvent(name);
+    }
+    /**
+     * A0 — unified event spine. Stamp the analytics identity (anonymous/user id) + the current replay
+     * coordinate onto a session-lane event item so ONE event carries full product context AND a
+     * replay-frame pointer. All additive (EventItemSchema passthrough); a no-op when analytics is off.
+     */
+    enrichEvent(item) {
+        const id = this.analyticsFeature()?.identity;
+        const replay = getReplayCoord();
+        // A1 — super-properties merge under the call-site props (explicit props win).
+        const sp = id?.superProps;
+        const itemProps = item.props;
+        const merged = sp && Object.keys(sp).length ? { ...sp, ...(itemProps ?? {}) } : itemProps;
+        // A3 — PII scrub the session-lane props too (parity with the analytics lane).
+        const props = merged ? scrubProps(merged) : merged;
+        return {
+            ...item,
+            ...(props !== undefined ? { props } : {}),
+            ...(id?.anonymousId ? { anonymousId: id.anonymousId } : {}),
+            ...(id?.userId ? { userId: id.userId } : {}),
+            ...(id?.groups && Object.keys(id.groups).length ? { groups: id.groups } : {}),
+            ...(replay ? { replay } : {}),
+        };
+    }
+    /** A1 — register global "super" properties merged into every subsequent event (persisted). */
+    register(props) {
+        this.analyticsFeature()?.register(props);
+        patchEvalContext(props); // F0 — super-props are targeting attributes
+    }
+    /** A1 — remove a previously-registered super-property. */
+    unregister(key) {
+        this.analyticsFeature()?.unregister(key);
+    }
+    /** A1 — associate the user with a B2B group (account/workspace). Stamps `groups` on every event +
+     *  emits a `$group` on both lanes so the backend upserts the group profile. */
+    group(groupType, groupKey, traits) {
+        if (!groupType || !groupKey)
+            return;
+        this.analyticsFeature()?.group(groupType, groupKey, traits); // updates groups BEFORE the enrich below
+        patchEvalContext({ [`group_${groupType}`]: groupKey }); // F0 — group membership as a targeting attribute
+        this.rt?.pipeline.emit(this.enrichEvent({ kind: 'event', name: '$group', props: { group_type: groupType, group_key: groupKey, ...(traits ?? {}) }, timestamp: now() }));
+    }
+    /** A1 — link the current identity to a prior id (anon→known / cross-device merge). */
+    alias(newUserId, previousId) {
+        if (!newUserId)
+            return;
+        const cur = this.analyticsFeature()?.identity;
+        const previous = previousId ?? cur?.userId ?? cur?.anonymousId;
+        this.analyticsFeature()?.alias(newUserId, previousId);
+        this.rt?.pipeline.emit({ kind: 'identify', userId: newUserId, previousId: previous, timestamp: now() });
+    }
+    /** A1 — logout: mint a fresh anonymous id + clear user/super-props/groups so the next user's events
+     *  aren't attributed to the previous one. */
+    reset() {
+        this.engageFeature()?.onLifecycle('before_logout'); // E1 — fire before we drop the identity
+        this.analyticsFeature()?.reset(); // mints a new anonymousId
+        clearEvalContext(); // F0 — drop the prior user's targeting attributes (keeps deviceId)
+        this.rt?.pipeline.emit({ kind: 'identify', reset: true, anonymousId: this.analyticsFeature()?.identity?.anonymousId, timestamp: now() });
+    }
+    /** A4 — record revenue (one-time / subscription / refund). Normalized revenue/currency + LTV props
+     *  to the analytics lane (server-deduped by transactionId) + a `purchase` event on the session lane
+     *  for replay/CWV-revenue correlation. Group attribution rides the stamped `groups`. */
+    trackPurchase(input) {
+        const norm = normalizeRevenue(input);
+        if (!norm)
+            return; // invalid (missing revenue/currency/transactionId) → drop from both lanes
+        this.rt?.pipeline.emit(this.enrichEvent({ kind: 'event', name: 'purchase', props: norm.props, revenue: norm.revenue, currency: norm.currency, timestamp: now() }));
+        this.analyticsFeature()?.trackPurchase(input);
+        this.engageFeature()?.onCustomEvent('purchase'); // E1 — feed the after_purchase trigger
+    }
+    /**
+     * W2 — record a subscription lifecycle change (trial/started/renewed/plan_changed/canceled/…) so the
+     * backend derives REAL MRR/ARR/churn/trials from an event-sourced ledger (not approximated from
+     * purchases). For production truth prefer posting from your billing webhook to the s2s endpoint; this
+     * client method is for billing-UI-driven changes. Validate-or-drop (invalid input is ignored).
+     */
+    trackSubscription(input) {
+        this.analyticsFeature()?.trackSubscription(input);
+    }
+    /**
+     * Report the current route/screen name — used by the framework adapters (router→route-name) to
+     * supply real route names instead of raw pathnames. Emits a SCREEN_VIEW with a top-level
+     * `screenName` so flows/funnels/journey pick it up.
+     */
+    trackScreen(name, props) {
+        if (!name)
+            return;
+        this.rt?.pipeline.emit(this.enrichEvent({ kind: 'event', name: 'SCREEN_VIEW', screenName: name, props, timestamp: now() }));
+        this.engageFeature()?.onScreenView(name); // feed Engage screen_view triggers
+    }
+    /** Attach user identity to the session + stamp it onto the analytics lane (links the profile). */
+    identify(userId, traits) {
+        // A0 — carry the current anonymousId so the backend links anon → identified deterministically
+        // (not just via the heuristic identity graph).
+        const anonymousId = this.analyticsFeature()?.identity?.anonymousId;
+        this.rt?.pipeline.emit({ kind: 'identify', userId, anonymousId, traits, timestamp: now() });
+        this.analyticsFeature()?.identify(userId, traits);
+        patchEvalContext({ userId, ...(traits ?? {}) }); // F0 — user id + traits are targeting attributes
+        // The boot config fetch was anonymous, and the backend serves no segment-targeted campaign to an
+        // anonymous request. Re-read it now that there is a user to resolve segments against — otherwise
+        // logging in mid-session shows nothing until the next full page load.
+        this.engageFeature()?.onIdentify();
+        this.rt?.registry.get('inapp2')?.onIdentify?.();
+    }
+    /** Set / merge the current user. */
+    setUser(user) {
+        if (user?.id)
+            this.identify(user.id, user);
+    }
+    /**
+     * Manually capture a handled error — routed through ErrorsFeature so normalization is shared.
+     * `info.componentStack` (from a React error boundary) rides along on the error item's metadata.
+     */
+    captureError(error, info) {
+        const extra = info?.componentStack ? { componentStack: info.componentStack } : undefined;
+        const over = info && (info.level || info.tags || info.context || info.fingerprint)
+            ? { level: info.level, tags: info.tags, context: info.context, fingerprint: info.fingerprint }
+            : undefined;
+        const errors = this.rt?.registry.get('errors');
+        if (errors?.captureHandled) {
+            errors.captureHandled(error, extra, over);
+            return;
+        }
+        // Fallback if the errors feature is disabled.
+        const e = error;
+        this.rt?.pipeline.emit({
+            kind: 'error',
+            type: 'handled',
+            message: e?.message ?? String(error),
+            stack: e?.stack,
+            source: 'js',
+            timestamp: now(),
+            ...(extra ?? {}),
+        });
+    }
+    /**
+     * Record a manual breadcrumb — an app-level milestone (e.g. "checkout: payment submitted") that
+     * joins the auto-captured trail (console/network/navigation/clicks) attached to the next error.
+     * Messages are scrubbed; the ring is bounded, so this is safe to call liberally.
+     */
+    addBreadcrumb(crumb) {
+        addCrumb({
+            ts: now(),
+            category: crumb.category ?? 'custom',
+            type: crumb.type,
+            level: crumb.level,
+            message: crumb.message,
+            data: crumb.data,
+        });
+    }
+    /** Set a searchable tag merged into every subsequent error (e.g. `setTag('plan','enterprise')`). */
+    setTag(key, value) {
+        setTag(key, value);
+    }
+    /** Attach arbitrary structured context merged into every subsequent error. */
+    setContext(key, value) {
+        setContext(key, value);
+    }
+    /** Set the default severity for subsequent errors (a captureError `level` overrides per-call). */
+    setErrorLevel(level) {
+        setErrorLevel(level);
+    }
+    /** Submit an in-app rating (an item in the same session). Rejects invalid scores (1–5). */
+    submitRating(score, comment, surveyId) {
+        const value = Math.round(score);
+        if (!Number.isFinite(value) || value < 1 || value > 5) {
+            this.rt?.log('[scalebun] submitRating: score must be an integer 1–5, got', score);
+            return;
+        }
+        const item = {
+            kind: 'rating',
+            score: value,
+            comment,
+            surveyId,
+            // Idempotency: a retried flush upserts on this id instead of duplicating (AppRating D8).
+            clientRatingId: `rat_${uuid()}`,
+            timestamp: now(),
+        };
+        this.rt?.pipeline.emit(item);
+    }
+    /**
+     * Submit a bug report (F-BUG). Auto-attaches the current session's evidence — it raises the
+     * 'report' capture-signal (so replay flushes its frame into the session) and includes recent
+     * console breadcrumbs; the dashboard joins network/errors/replay by sessionId. Returns the created
+     * report id, or null on failure / when the feature is disabled. Anonymous reports are allowed.
+     */
+    /**
+     * Declare where INLINE in-app messages may render.
+     *
+     * Four formats (`inline_card`, `embedded_panel`, `empty_state_prompt`, `smart_inbox_message`)
+     * belong in the page rather than over it, and the SDK cannot guess where. Register an element
+     * whose name matches the campaign's placement key and those campaigns render in place; without a
+     * matching slot they keep falling back to a modal, so calling this is purely additive.
+     *
+     * Returns an unregister function — call it on unmount, or messages will render into a detached
+     * element, which looks exactly like them not rendering at all.
+     *
+     * Dynamic-imported so a host that never places inline messages pays nothing for the registry.
+     */
+    async registerInAppSlot(name, el) {
+        const { registerInAppSlot } = await import('../features/engage/inappSlots');
+        return registerInAppSlot(name, el);
+    }
+    async reportBug(input) {
+        if (!this.rt)
+            return null;
+        if (this.rt.config.features.bugReport === false) {
+            this.rt.log('[scalebun] reportBug: bugReport feature is disabled');
+            return null;
+        }
+        if (!input || !input.message) {
+            this.rt.log('[scalebun] reportBug: a message is required');
+            return null;
+        }
+        // Consent gate: reportBug sends DIRECTLY via transport (bypassing pipeline.emit), so honor the
+        // same egress gate here — never POST a report (message/email/breadcrumbs) while consent is denied.
+        if (!this.rt.pipeline.canEgress()) {
+            this.rt.log('[scalebun] reportBug: blocked — consent not granted');
+            return null;
+        }
+        try {
+            // 1) Flush replay into the session so the report has its visual context.
+            const bug = this.rt.registry.get('bugReport');
+            bug?.signalReport?.();
+            // 2) Grab recent console breadcrumbs (full set is already in-session).
+            const consoleFeature = this.rt.registry.get('console');
+            const recent = consoleFeature?.getRecent?.() ?? [];
+            // 3) Build + submit; flush so the replay frame egresses promptly.
+            const payload = buildBugReportPayload({ message: input.message, title: input.title, email: input.email }, recent);
+            const res = await this.rt.transport.submitBugReport(this.rt.session.sessionId, payload);
+            await this.rt.pipeline.flush();
+            return res?.id ?? null;
+        }
+        catch {
+            return null; // never throw into the host app
+        }
+    }
+    /** Force an immediate flush of BOTH egress lanes (session pipeline + analytics /batch). */
+    async flush() {
+        await Promise.all([this.rt?.pipeline.flush(), this.analyticsFeature()?.flush()]);
+    }
+    /** The SDK's own error-pipeline health (captured / dropped / by-type / breadcrumb count). */
+    errorStats() {
+        const errors = this.rt?.registry.get('errors');
+        return errors?.stats?.() ?? null;
+    }
+    /** The SDK's own RUM health (transactions / dropped / resources / jank / sample rate). */
+    perfStats() {
+        const perf = this.rt?.registry.get('performance');
+        return perf?.perfStats?.() ?? null;
+    }
+    /** The SDK's own network-capture health (captured / by-protocol / by-failure / dropped / bodies). */
+    networkStats() {
+        const net = this.rt?.registry.get('network');
+        return net?.stats?.() ?? null;
+    }
+    /** End the session and stop capture. */
+    async close() {
+        this.rt?.registry.teardownAll();
+        await this.rt?.pipeline.stop();
+        this.rt = null; // fully reset so sessionId/stats/methods report "not running" and re-init is clean
+        this.ready = false;
+    }
+    get sessionId() {
+        return this.rt?.session.sessionId;
+    }
+    /**
+     * Egress telemetry for debugging / a Dev Panel: items still waiting to send, and items dropped
+     * (queue overflow or stale-on-reload), summed across the session pipeline + analytics lane.
+     */
+    egressStats() {
+        const a = this.analyticsFeature();
+        return {
+            pending: (this.rt?.pipeline.pendingCount ?? 0) + (a?.pending ?? 0),
+            dropped: (this.rt?.pipeline.dropped ?? 0) + (a?.dropped ?? 0),
+        };
+    }
+    /** A7 — product-analytics lane observability: events pending/dropped/sampled-out, successful
+     *  flushes, and the active sample rate. Null when analytics isn't running. */
+    analyticsStats() {
+        return this.analyticsFeature()?.stats ?? null;
+    }
+    // ── Analytics (F-ANL) — product-analytics + revenue lane ───────────────────────
+    analyticsFeature() {
+        return this.rt?.registry.get('analytics');
+    }
+    replayFeature() {
+        return this.rt?.registry.get('replay');
+    }
+    // ── Engage (F-ENG) — surveys / NPS ─────────────────────────────────────────────
+    engageFeature() {
+        return this.rt?.registry.get('engage');
+    }
+    // ── Inbox (F-INBOX) — persistent message center ────────────────────────────────
+    inboxFeature() {
+        return this.rt?.registry.get('inbox');
+    }
+    /** The persistent message inbox. Returns a stable headless controller (reactive subscribe + verbs).
+     *  When `features.inbox` is off (default until GA) this is a safe no-op so hosts never crash. */
+    inbox() {
+        return this.inboxFeature()?.controller() ?? NOOP_INBOX;
+    }
+    // ── Coachmarks (F-COACH) — lazy: the engine loads only on first coachmarks() use (0 eager cost) ──
+    ensureCoach() {
+        if (this.coachFeature)
+            return Promise.resolve(this.coachFeature);
+        if (!this.rt)
+            return Promise.resolve(null);
+        return import('../features/coach/CoachmarkFeature').then(({ CoachmarkFeature }) => {
+            if (this.coachFeature)
+                return this.coachFeature;
+            const deps = {
+                trackEvent: (n, p) => this.track(n, p),
+                replayCoord: getReplayCoord,
+                apiBaseUrl: this.rt?.config.apiBaseUrl,
+                clientKey: this.rt?.config.clientKey,
+            };
+            const f = new CoachmarkFeature(deps);
+            this.coachFeature = f;
+            return f;
+        });
+    }
+    /** Coachmark tours — start/next/back/skip/end, subscribe to `$coachmark_*` events, or `notify()` a
+     *  custom-event advance. Every step is replayCoord-stamped (watch the frame a user abandoned a step). */
+    coachmarks() {
+        if (this.coachController)
+            return this.coachController;
+        const run = (fn) => { void this.ensureCoach().then((f) => { if (f)
+            fn(f); }); };
+        this.coachController = {
+            start: (tour, opts) => run((f) => f.start(tour, opts)),
+            startInline: (tour) => run((f) => f.start(tour)),
+            startById: (id, opts) => run((f) => void f.startById(id, opts)),
+            reportAnchors: () => run((f) => f.reportAnchors()),
+            next: () => run((f) => f.next()),
+            back: () => run((f) => f.back()),
+            skip: () => run((f) => f.skip()),
+            end: () => run((f) => f.end()),
+            notify: (event) => run((f) => f.notify(event)),
+            current: () => this.coachFeature?.current() ?? { tourId: null, index: 0, status: 'idle' },
+            on: (event, cb) => {
+                if (this.coachFeature)
+                    return this.coachFeature.on(event, cb);
+                let real = null;
+                let cancelled = false;
+                void this.ensureCoach().then((f) => { if (f && !cancelled)
+                    real = f.on(event, cb); });
+                return () => { cancelled = true; real?.(); };
+            },
+        };
+        return this.coachController;
+    }
+    // ── Web Push (F-PUSH, E4) — lazy: the module loads only when enablePush() is first called ────────
+    /** Lazy-load + construct the PushFeature once (needs the resolved apiBaseUrl/clientKey/deviceId). */
+    async ensurePush() {
+        if (this.pushFeature)
+            return this.pushFeature;
+        if (!this.rt)
+            return null;
+        const { PushFeature } = await import('../features/push/PushFeature');
+        this.pushFeature = new PushFeature({
+            apiBaseUrl: this.rt.config.apiBaseUrl,
+            clientKey: this.rt.config.clientKey,
+            deviceId: this.rt.session.deviceId,
+            log: this.rt.log,
+        });
+        // E6 — a push open auto-emits `$push_opened`, which flows through track() → enrichEvent and is
+        // stamped with the current replay coordinate: the dashboard deep-links to the frame the visitor
+        // landed on from the notification (open → session → exact frame). No survey/push vendor does this.
+        this.pushFeature.onNotificationOpened(({ data, action }) => {
+            this.track('$push_opened', {
+                ...(action ? { action } : {}),
+                ...(data && typeof data === 'object' ? data : {}),
+            });
+        });
+        // Flush any callbacks registered before the module loaded.
+        for (const cb of this.pendingPushOpenCbs)
+            this.pushFeature.onNotificationOpened(cb);
+        this.pendingPushOpenCbs = [];
+        return this.pushFeature;
+    }
+    /**
+     * E4 — opt into Web Push. MUST be called from a user gesture (browsers gate the notification
+     * prompt). Feature-detects + fetches the tenant VAPID key, registers the host-served service worker
+     * (`/scalebun-push-sw.js`), subscribes, and registers the browser PushSubscription with the backend.
+     * Resolves a status string — never throws. No-op ('unsupported'/'not-configured'/'denied') when the
+     * browser lacks support, the tenant hasn't set Web Push up, or the user declined.
+     */
+    async enablePush(opts) {
+        const push = await this.ensurePush();
+        return push ? push.enable(opts) : 'error';
+    }
+    /**
+     * E4 — subscribe to notification-open events (fired when the user clicks a push). Safe to call
+     * before enablePush(): the callback is buffered and attached once the push module loads. Returns an
+     * unsubscribe function.
+     */
+    onNotificationOpened(cb) {
+        if (this.pushFeature)
+            return this.pushFeature.onNotificationOpened(cb);
+        this.pendingPushOpenCbs.push(cb);
+        // Kick the lazy load so the SW-message bridge is bound even without an enablePush() call yet.
+        void this.ensurePush();
+        return () => {
+            this.pushFeature?.onNotificationOpened(cb); // if loaded, re-registering is idempotent via the Set
+            const i = this.pendingPushOpenCbs.indexOf(cb);
+            if (i >= 0)
+                this.pendingPushOpenCbs.splice(i, 1);
+        };
+    }
+    // ── Config & flags (F-CFG) — all delegate to the ConfigFeature; crash-safe defaults if absent ──
+    cfg() {
+        return this.rt?.registry.get('config');
+    }
+    /**
+     * A5 — record a feature-flag / experiment exposure so analytics can attribute behaviour to it:
+     *  (1) stamp `$feature/<key>` as a super-property → EVERY downstream event carries the assignment
+     *      (experiment-attributable with no join), and
+     *  (2) emit one `$feature_flag_called` per (flag, value) per session (PostHog-style; internal `$`
+     *      event, so it's never governed).
+     * No-op before init (a later read re-attempts) and for null variants.
+     */
+    recordExposure(key, value, reason) {
+        if (!this.rt || value == null)
+            return;
+        const dedup = `${key}=${String(value)}`;
+        if (this.flagExposed.has(dedup))
+            return;
+        this.flagExposed.add(dedup);
+        this.analyticsFeature()?.register({ [`$feature/${key}`]: value });
+        // F6 — stamp the evaluation reason (TARGETING_MATCH | ROLLOUT | DEFAULT | …) so analytics can
+        // segment exposures by WHY the user was served, not just what.
+        this.track('$feature_flag_called', { flag_key: key, flag_value: value, ...(reason ? { reason } : {}) });
+    }
+    // ── Profiler (F-PROF) — JS Self-Profiling flame graphs (opt-in) ─────────────────
+    prof() {
+        return this.rt?.registry.get('profiler');
+    }
+}
+/** No-op inbox controller returned when `features.inbox` is disabled — every method is safe.
+ *  Shared `_no`/`_res`/`_s0` refs keep the eager byte cost minimal (core-gate discipline). */
+const _no = () => { };
+const _res = () => Promise.resolve();
+const _s0 = { unreadCount: 0, total: 0, syncStatus: 'idle' };
+const NOOP_INBOX = {
+    subscribe: (cb) => (cb(_s0), _no),
+    onUnreadChange: (cb) => (cb(0), _no),
+    getState: () => _s0,
+    query: () => Promise.resolve({ messages: [], cursor: null, hasMore: false }),
+    get: () => Promise.resolve(undefined),
+    markRead: _res, markUnread: _res, markAllRead: _res, archive: _res, unarchive: _res,
+    pin: _res, remove: _res, refresh: _res, ingest: _res,
+    act: _no,
+    onCtaAction: () => _no,
+    mount: _no,
+    open: _no,
+    close: _no,
+    unmount: _no,
+};
+/** The default export consumers import. */
+export const ScaleBun = new ScaleBunFacade();
+//# sourceMappingURL=ScaleBunFacade.js.map