@scalebun-release/react-native 2.5.0

package/lib/typescript/features/journey/uiState.d.ts

@@ -0,0 +1,93 @@
+/**
+ * UI STATE AT INTERACTION TIME — React Native.
+ *
+ * A screen is not just `Cart`. It is `Cart` with the filter sheet down, or up; with the address form
+ * expanded, or collapsed. Those are different interaction surfaces and a tap on one must never be
+ * counted on another — heat from the open sheet painted over the closed layout is a picture of
+ * something that never existed.
+ *
+ * HOW THIS DIFFERS FROM THE WEB, and the difference is not an omission:
+ *
+ *   The web SDK ALSO detects state automatically, by reading `aria-expanded` and open `<dialog>`
+ *   elements out of the live DOM. Those are platform-defined, so reading them is a measurement.
+ *
+ *   React Native has no equivalent. There is no queryable tree of accessibility state that says a
+ *   bottom sheet is up; a sheet is a component with a boolean in someone's store, and the only place
+ *   that boolean exists is the host's own code. Guessing at it — from a modal's presence in the tree, or
+ *   from a component name — would produce a state key that is right on some apps and silently wrong on
+ *   others, and a wrong state key partitions taps into buckets corresponding to nothing.
+ *
+ * So on RN, state is DECLARED and never inferred. `ScaleBun.setUiState('filter-sheet', 'open')` is the
+ * whole mechanism, and its absence means "not captured" rather than "nothing was open". That
+ * distinction is carried all the way to the dashboard: a tap with no declared state is NULL, not '',
+ * and cannot be selected as a state or counted as one. Reporting it as "nothing was open" would be
+ * asserting a measurement nobody took.
+ *
+ * PAIRED WITH: whatzbug-web-sdk/packages/web/src/features/journey/uiState.ts — same wire format
+ * (`name:value` pairs, sorted, `;`-joined, <= 96 chars), same separator stripping, same explicit-wins
+ * precedence, so one dashboard control queries both platforms.
+ */
+export declare function uiStateInstrumented(): boolean;
+/**
+ * Declare the state of one UI dimension.
+ *
+ * Call it when the state CHANGES, not on every render: the value is read at interaction time, so it
+ * only has to be correct by the time the next tap lands.
+ */
+export declare function setUiState(name: string, value: string): void;
+/**
+ * Stop reporting a dimension — or, with no name, all of them.
+ *
+ * Later taps carry no value for it, which is not the same as carrying a value. Clearing all is what a
+ * screen unmount wants: declarations from the previous screen would otherwise follow the user onto a
+ * surface where they mean nothing, and every tap there would be filed under a state that was not on
+ * screen.
+ */
+export declare function clearUiState(name?: string): void;
+/**
+ * The signature for the interaction happening RIGHT NOW, or undefined when nothing is declared.
+ *
+ * undefined rather than '' deliberately — see the header. '' is the web's "we looked and nothing was
+ * open"; on RN there is nothing to look at, so the honest answer is silence.
+ */
+export declare function uiStateSignature(): string | undefined;
+/**
+ * RN-11 — TELL SOMEONE THE STATE CHANGED, so a frame can exist for it.
+ *
+ * THE GAP. Declaring a state used to mutate a Map and nothing else. Nothing captured a frame, so
+ * the visual for a declared state existed only if a screenshot happened to be taken for some other
+ * reason — a navigation, a timer, or the interaction capture that fires AFTER the touch and
+ * photographs the outcome. A state could therefore be recorded as a fact with no picture of it
+ * anywhere, or with a picture of the state that replaced it.
+ *
+ * The native capture reasons are NAVIGATION, MANUAL, INTERACTION and TIMER. None of them is "the
+ * UI changed shape", which is exactly the moment a heatmap needs a frame.
+ *
+ * FIRING ON A REAL CHANGE ONLY, AND WHY THAT IS THE SDK'S JOB. The advice above says to call
+ * `setUiState` when the state changes rather than on every render — but that is advice to the
+ * host, not a guarantee. A component that declares its state inside render is ordinary React, and
+ * trusting the caller would mean a screenshot per render: a performance disaster in exactly the
+ * apps that instrument most carefully. So a redundant set — same dimension, same value — is now a
+ * no-op, and the change test lives here where it cannot be got wrong by a host.
+ *
+ * COALESCED, because a transition usually declares several dimensions in one tick ("drawer:open"
+ * and "overlay:visible" belong to one visual change). Notifying per call would capture the
+ * intermediate shapes, which are states the user never saw.
+ *
+ * The listener is deliberately NOT given the signature. A subscriber that wants it calls
+ * `uiStateSignature()` at the moment it acts, which is the value that will actually be attached
+ * to the next tap; handing over a snapshot invites acting on a state that has already moved on.
+ */
+export type UiStateChangeListener = () => void;
+/**
+ * Subscribe to declared-state changes. Returns an unsubscribe.
+ *
+ * Registration is idempotent per function reference, so a component that re-subscribes on every
+ * render does not accumulate listeners — a leak that would only show up in long sessions.
+ */
+export declare function onUiStateChange(listener: UiStateChangeListener): () => void;
+/** Drop every listener and any pending notification. For teardown between sessions. */
+export declare function resetUiStateListeners(): void;
+/** For assertions that a re-subscribing caller has not leaked. */
+export declare function uiStateListenerCount(): number;
+//# sourceMappingURL=uiState.d.ts.map

package/lib/typescript/features/navigation/AutoScreenDetector.d.ts

@@ -0,0 +1,196 @@
+/**
+ * ScaleBun SDK — Auto Screen Detector
+ *
+ * Automatically detects the current screen/route from React Navigation
+ * WITHOUT requiring per-screen `<ScaleBunScreen>` beacons.
+ *
+ * Precedence rules (deterministic, no oscillation):
+ *   1. Manual override via `useScaleBunScreen()` / `<ScaleBunScreen>` ALWAYS wins
+ *   2. Explicit navigation ref (via `setNavigationRef()`) wins over heuristics
+ *   3. Heuristic polling (best-effort) is the last fallback
+ *
+ * The detector is idempotent, no-throw, safe to call multiple times,
+ * and safe when navigation is unavailable.
+ */
+interface ScreenChangeCallback {
+    (screenName: string, source: 'manual' | 'navRef' | 'heuristic'): void;
+}
+/**
+ * AutoScreenDetector — singleton that auto-detects the active screen.
+ *
+ * Does NOT use undocumented `(global).__reactNavigation` as a primary mechanism.
+ * Instead:
+ *   1. `setNavigationRef(ref)` — explicit, reliable, developer-provided
+ *   2. Heuristic navigation state polling — best-effort fallback using
+ *      common React Navigation patterns
+ *   3. Manual `useScaleBunScreen()` always overrides — via `setManualScreen()`
+ */
+export declare class AutoScreenDetector {
+    private _listeners;
+    private _manualScreen;
+    private _manualScreenTs;
+    private _autoScreen;
+    /**
+     * When `_autoScreen` was last written.
+     *
+     * Needed so `getCurrentScreen()` can prefer whichever source spoke MOST RECENTLY.
+     * Without a timestamp the only comparison available was "is the manual value still
+     * fresh", which is a different question and gave the wrong answer — see the note on
+     * `_currentScreen()`.
+     */
+    private _autoScreenTs;
+    /** `name#key` of the last auto-detected screen VISIT — see _extractActiveVisit. */
+    private _autoVisitSig;
+    private _navigationRef;
+    private _navListenerRemover;
+    private _navListenerWired;
+    private _heuristicTimer;
+    private _started;
+    private _lastEmittedScreen;
+    private _lastEmittedTs;
+    /**
+     * Cross-source emit dedup window — see _emitScreenChange. Long enough to absorb the manual
+     * beacon and the navRef listener both reporting the SAME transition (they land within the
+     * 30ms nav debounce plus a render), short enough that a genuine re-visit of the same route
+     * a moment later is a new screen view rather than silence.
+     */
+    private static readonly EMIT_DEDUP_WINDOW_MS;
+    private _navDebounceTimer;
+    /** Whether the React Navigation exports were actually replaced — see _autoHookReactNavigation. */
+    private _autoHookInstalled;
+    /** Cooldown: after manual screen is set, suppress auto-detection for this duration */
+    private static MANUAL_COOLDOWN_MS;
+    /** Heuristic polling interval */
+    private static HEURISTIC_POLL_MS;
+    static getInstance(): AutoScreenDetector;
+    /** Register a callback for screen changes */
+    onScreenChange(cb: ScreenChangeCallback): () => void;
+    /**
+     * Set screen name from manual instrumentation (`useScaleBunScreen` / `<ScaleBunScreen>`).
+     * This ALWAYS takes precedence over auto-detection.
+     */
+    setManualScreen(name: string): void;
+    /**
+     * Clear manual override. Auto-detection may resume after cooldown.
+     */
+    clearManualScreen(): void;
+    /**
+     * Set screen name from native lifecycle detection (Android Activity / iOS ViewController).
+     * Lower priority than manual override — yields when manual is active.
+     * Use this when native code auto-detects the current screen without JS navigation.
+     */
+    setNativeScreen(name: string): void;
+    /**
+     * Should a WRITER defer to the manual screen right now?
+     *
+     * THIS IS A PRECEDENCE GATE, NOT A VALIDITY TEST, and conflating the two was a real
+     * bug. Its job is what the cooldown constant says: for a short window after a manual
+     * beacon fires, an auto source must not overwrite it — the poller runs every 1500 ms
+     * and would otherwise clobber a fresh declaration with whatever it inferred.
+     *
+     * `getCurrentScreen()` used to reuse this as "is the manual screen still the current
+     * screen", which made a declared screen READABLE for only 2000 ms. Nothing called
+     * `setManualScreen` in production, so the effect was latent — but the moment the
+     * `<ScaleBunScreen>` beacon was wired to it (RN-8), every tap more than two seconds
+     * after a screen mounted would have lost its name, which is very nearly every tap. A
+     * fix that introduced that would have been worse than the gap it closed.
+     */
+    isManualScreenActive(): boolean;
+    /**
+     * Set an explicit React Navigation container ref.
+     * This is the most reliable auto-detection mechanism.
+     *
+     * @param ref - A React Navigation `NavigationContainerRef`
+     */
+    setNavigationRef(ref: any): void;
+    private _wireNavigationListener;
+    /**
+     * Start the heuristic polling fallback.
+     * This periodically checks for React Navigation state via common patterns.
+     * Only fires if no manual screen or explicit nav ref is active.
+     */
+    private _startHeuristicPolling;
+    /**
+     * Best-effort: try to locate a navigation container.
+     * Checks common global locations, returns null if none found.
+     */
+    private _findNavigationContainer;
+    /**
+     * Extract the active route name from a navigation state tree.
+     * Handles nested navigators by walking to the deepest active route.
+     */
+    private _extractActiveRoute;
+    /**
+     * Extract the active route's name AND its React Navigation route `key`.
+     *
+     * The key is what makes re-VISITS detectable. Comparing names alone collapses two
+     * different visits to the same route into one screen view: leave Details, open Details
+     * again, and `name === _autoScreen` swallowed the second visit entirely (QA: "opened the
+     * same route again and no screen event was recorded"). React Navigation mints a fresh
+     * `key` for every pushed route instance, so a re-push of the same name is a NEW key —
+     * name+key comparison records each visit while a mere re-render of the same instance
+     * (same key) still emits nothing. States without keys degrade to name-only, i.e. the
+     * old behaviour, never worse.
+     */
+    private _extractActiveVisit;
+    /** `name#key` signature of one screen VISIT — what the auto paths dedup on. */
+    private _visitSig;
+    /** Start auto-detection (idempotent) */
+    start(): void;
+    /**
+     * Zero-config React Navigation hook.
+     *
+     * Patches the three public entry points apps use to obtain a navigation
+     * container so the SDK captures the container ref WITHOUT the app wiring
+     * `setNavigationRef()` / `<ScaleBunDebugRoot navigationRef>`. Best-effort and
+     * no-throw: if `@react-navigation/native` isn't installed, or an entry point
+     * is missing, we silently skip and the heuristic poller remains the fallback.
+     *
+     * Once any container ref is captured, `setNavigationRef()` wires the
+     * documented `'state'` listener and the existing pipeline emits screen
+     * changes (→ SessionManager SCREEN_VIEW + navigation-triggered frames).
+     */
+    private _autoHookReactNavigation;
+    /**
+     * Did the zero-config hook actually take effect?
+     *
+     * Exposed because "we tried" and "it worked" were previously the same observable state, and the
+     * difference between them is every screen name in the product.
+     */
+    isAutoHookInstalled(): boolean;
+    /** Stop auto-detection and clean up */
+    stop(): void;
+    /** Teardown completely (reset singleton) */
+    teardown(): void;
+    /** Get the current best-known screen name */
+    getCurrentScreen(): string | null;
+    /**
+     * WHERE the current screen name came from, or 'none'.
+     *
+     * Recorded on every interaction (RN-8) so low screen coverage is DIAGNOSABLE rather
+     * than merely visible. Production shows 13.8% of Android interactions carrying a
+     * screen and 0.5% on iOS, and those numbers cannot today distinguish three different
+     * causes: the app never instrumented anything, the app instrumented manually and the
+     * value never reached interactions, or auto-detection ran and failed. Those have
+     * different owners and different fixes, and guessing between them is how a P0 stays
+     * open.
+     */
+    getCurrentScreenSource(): 'manual' | 'navigation' | 'none';
+    /**
+     * LAST WRITER WINS between the manual beacon and auto-detection.
+     *
+     * A screen declared by `<ScaleBunScreen name>` stays current until something else
+     * declares a different one — that is what mounting a screen means. It does not
+     * expire, which is the correction here: the previous rule returned the manual name
+     * only while it was under 2000 ms old and then silently fell back to the auto value,
+     * which in a manually-instrumented app is `null`.
+     *
+     * Comparing timestamps rather than hard-coding a priority also handles the real
+     * interleaving: an app can use React Navigation for most screens AND drop a manual
+     * beacon on one modal, and whichever spoke last is the truth.
+     */
+    private _currentScreen;
+    private _emitScreenChange;
+}
+export {};
+//# sourceMappingURL=AutoScreenDetector.d.ts.map

package/lib/typescript/features/network/NetworkFeature.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ScaleBun SDK — Network Feature
+ *
+ * Wraps network monitoring behind the IFeature interface.
+ * Installs XHR and Fetch interceptors and routes captured network
+ * events through the SDK pipeline.
+ *
+ * INTERCEPTION ARCHITECTURE:
+ * The actual request interception logic lives in:
+ *   - `integrations/xhr/xhrInterceptor.ts`   (XMLHttpRequest monkey-patch)
+ *   - `integrations/fetch/fetchInterceptor.ts` (global fetch wrapper)
+ * This class is only the lifecycle wrapper — it calls
+ * `installNetworkMonitoring()` (from `features/network/index.ts`)
+ * which delegates to both interceptors.
+ *
+ * Accepts `NetworkMonitoringOptions` to opt in to header/body capture
+ * via `captureNetworkBodies: true`. Default is false (capture is opt-in).
+ *
+ * ⚠️  PRIVACY: Enabling `captureNetworkBodies` may capture sensitive user
+ * data. See `ScaleBunFeatures.captureNetworkBodies` for the full warning.
+ *
+ * SOLID: Single Responsibility — only manages network interception lifecycle.
+ * SOLID: Open/Closed — added without modifying existing interceptors.
+ */
+import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
+import { type NetworkMonitoringOptions } from './index';
+/**
+ * The interceptors intentionally expose structured JSON and marker objects so
+ * replay/debug consumers can inspect them. The dedicated ingestion contract is
+ * text-based, therefore serialize exactly once at that boundary.
+ */
+export declare function serializeNetworkBody(body: unknown): string | undefined;
+export declare class NetworkFeature implements IFeature {
+    readonly name = "network";
+    private active;
+    private trackFn;
+    private options;
+    constructor(trackFn: (name: string, payload?: Record<string, unknown>) => void, options?: NetworkMonitoringOptions);
+    initialize(_context: FeatureContext): void;
+    teardown(): void;
+    get isActive(): boolean;
+}
+//# sourceMappingURL=NetworkFeature.d.ts.map

package/lib/typescript/features/network/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ScaleBun SDK — Network Monitoring Entry Point
+ *
+ * Installs both XHR and fetch interceptors.
+ * Accepts network capture options so callers can opt in to body capture.
+ */
+export interface NetworkMonitoringOptions {
+    /** Capture request/response headers and bodies. Default: false */
+    captureNetworkBodies?: boolean;
+    /** Max bytes to capture per body before truncating. Default: 65536 */
+    networkBodyMaxBytes?: number;
+    /** Apply redaction pipeline to captured headers/bodies. Default: false */
+    redactNetwork?: boolean;
+    /** SDK backend base URL — used to filter out SDK's own upload calls from capture */
+    sdkBaseUrl?: string;
+    /**
+     * Never capture requests whose URL matches (substring or RegExp).
+     *
+     * Parity with the web SDK, which has had this since F-NET. Mobile had no way to exclude a
+     * URL at all, so an app that wanted one endpoint out of its replays had no answer.
+     */
+    denyUrls?: (string | RegExp)[];
+    /**
+     * Keep known telemetry beacons: analytics collectors, ad pixels, IP-enrichment calls.
+     *
+     * Default false — they are dropped before capture. They are not the app, they cost the
+     * device real battery and cellular data to upload, and a beacon that fails counts against
+     * the SESSION HEALTH score. Matching is by hostname only, never by path, so an app route
+     * called /collect is never touched. See features/network/thirdParty.ts.
+     */
+    captureThirdParty?: boolean;
+    /** Replace the built-in beacon host list wholesale. Comma-joined hostname suffixes. */
+    thirdPartyHosts?: string;
+    /**
+     * Raised as a request starts and again as it ends, for consumers that need to know the app
+     * is WAITING rather than what it waited for. Passed to both interceptors unchanged.
+     *
+     * RN implements `fetch` over XMLHttpRequest, so one app-level fetch reports through both and
+     * is counted twice. That is harmless here precisely because the signal is a balanced pair:
+     * two starts are matched by two ends, and the only consumer asks whether the count is zero.
+     * Anything that needed per-request identity would have to dedupe first.
+     */
+    onRequestPhase?: (phase: 'start' | 'end', url: string) => void;
+}
+export declare function installNetworkMonitoring(onEvent: (data: any) => void, options?: NetworkMonitoringOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/features/network/thirdParty.d.ts

@@ -0,0 +1,95 @@
+/**
+ * THIRD-PARTY BEACON HOSTS — the one list, and the one matcher, for every layer that drops them.
+ *
+ * WHAT THIS IS FOR
+ * A session on an instrumented site spends most of its network tab on traffic the app did not
+ * meaningfully make: analytics collectors, ad pixels, IP-enrichment calls, tag managers. It is
+ * captured, uploaded, stored and rendered, and none of it answers a question anyone asks a session
+ * replay. One real sign-in screen was 27 requests, most of them beacons.
+ *
+ * It is not only clutter. Session health scores `failedRequests` and `slowRequests`, so a tracker
+ * killed by an ad blocker (a transport error) or one that is simply slow moves a number that is
+ * supposed to describe the APP. That is the part that makes this a correctness fix rather than a
+ * tidy-up.
+ *
+ * WHY HOSTS ONLY, NEVER PATHS
+ * The obvious rules from looking at a network tab are `/collect`, `/p`, `/api/v2/pixel`. Every one
+ * of them is a path that a customer's own API is allowed to have, and dropping a real API call is
+ * far worse than keeping a beacon: the noise is visible and annoying, the missing request is
+ * invisible and misleading. So matching is on the HOSTNAME, with a dot boundary, and a request to
+ * `/collect` on the app's own origin is kept — correctly.
+ *
+ * WHY IT IS A SUFFIX LIST AND NOT A REGEX
+ * Two reasons, both practical. It is applied inside an SDK whose eager bundle is measured in bytes,
+ * and a comma-joined string of suffixes compresses to almost nothing next to an equivalent pattern
+ * source. And it has to be COPIED, byte for byte, into the React Native SDK and into the backend's
+ * ingest path — a list with no syntax is a list that cannot drift in meaning between three
+ * languages' worth of tooling. `third-party:parity` hashes all three copies.
+ *
+ * ZERO IMPORTS, DELIBERATELY. That is what makes the byte-identical copy possible. If an edit here
+ * ever needs an import, the parity gate is the thing that will say so — keep the module pure rather
+ * than weakening the gate.
+ *
+ * WHAT IS DELIBERATELY NOT ON THE LIST
+ * The rule is: a host whose ONLY purpose is to receive telemetry. Everything else stays, because a
+ * dropped request is invisible and a kept one is merely noisy.
+ *
+ *   - Feature-flag and experiment services (LaunchDarkly, Optimizely, Split). Their RESPONSES
+ *     change what the app does, so a failed flag fetch is an application incident and the single
+ *     most useful request in the session.
+ *   - Chat and support widgets (Intercom, Zendesk, Drift). A broken widget is a broken feature the
+ *     user can see.
+ *   - `facebook.com` as a whole. `graph.facebook.com` is an API real apps call; only the pixel
+ *     delivery hosts are listed.
+ *   - CDNs of any kind, even ones that mostly serve tags: they also serve application assets, and
+ *     dropping them would hide a real asset failure.
+ *
+ * When in doubt, leave it out. `denyUrls` stays the per-app escape hatch in both SDKs, and it can
+ * do what this list will not.
+ */
+/**
+ * Known telemetry, advertising and enrichment endpoints, as hostname suffixes.
+ *
+ * One comma-joined string rather than an array: identical meaning, materially smaller once gzipped,
+ * and it keeps the copy in three repos a single line to compare by eye.
+ */
+export declare const THIRD_PARTY_BEACON_HOSTS: string;
+/**
+ * True when `url` is addressed to a known beacon host.
+ *
+ * Deliberately total: an unparseable or relative URL is NOT third party. A relative URL is
+ * same-origin by definition — the app's own call — and guessing on garbage input would drop real
+ * requests for no benefit.
+ */
+export declare function isThirdPartyBeacon(url: string, hosts?: string): boolean;
+/**
+ * WHAT A CAPTURED REQUEST IS — the general rule, so a new client's traffic needs no new list entry.
+ *
+ * The host list above only knows the trackers someone has already seen. On production the network
+ * table was ~92% requests that were not the app's own API calls (2026-09-22: 1.13M tracker beacons,
+ * 1.10M Next.js page payloads, 136k CDN analytics beacons, 31k browser-internal URLs, of 2.6M rows),
+ * and every one of them also moved session health as a failed or slow request. So a request is
+ * classified by what ANY client's traffic carries, and only `api` is kept:
+ *
+ *   other      not http(s)/ws(s): `properties://`, `chrome-extension://`, `blob:`, `data:` —
+ *              browser and extension internals, never the app's backend.
+ *   telemetry  sent with `navigator.sendBeacon` (protocol 'beacon'): fire-and-forget, no response,
+ *              so it has no status or latency worth scoring — it is how analytics and pixels send.
+ *              Plus Cloudflare's `/cdn-cgi/rum` (a path Cloudflare reserves on every zone it
+ *              proxies), the `/generate_204` connectivity probe, and the known hosts above.
+ *   page       framework page-data payloads, fetched on navigation and on link PREFETCH:
+ *              Next.js `?_rsc=` and `/_next/data/…json`, Remix `?_data=routes…|root`, SvelteKit
+ *              `/__data.json`, Nuxt `/_payload.json`, Gatsby `/page-data/…json`.
+ *   asset      image, font, stylesheet, script and media files by extension. `.json`, `.pdf`,
+ *              `.csv` are NOT assets — those are what an API returns.
+ *   api        everything else — including anything unparseable, per the rule above: a dropped
+ *              API call is invisible data loss, a kept beacon is only noise.
+ *
+ * Deliberately NOT a signal: `fetch(…, {keepalive: true})`. Apps use it for their own save-on-leave
+ * calls, and those are exactly the requests whose failure matters.
+ */
+export type RequestKind = 'api' | 'telemetry' | 'page' | 'asset' | 'other';
+export declare function requestKind(url: string, protocol?: string, hosts?: string): RequestKind;
+/** True when the request is one of the app's own API calls — the only kind the network lane keeps. */
+export declare function isAppRequest(url: string, protocol?: string, hosts?: string): boolean;
+//# sourceMappingURL=thirdParty.d.ts.map

package/lib/typescript/features/ota/OtaEventEmitter.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Typed OTA event bus — emits lifecycle events consumed by:
+ *  1. The `useOtaUpdate` hook (UI progress / status)
+ *  2. The telemetry pipeline (batched to backend as `ota_event` items)
+ *
+ * Sprint 5 deliverable (S5-NAT-2, S5-NAT-3).
+ */
+export type OtaEventType = 
+/** A check was made against the server. The denominator of the funnel. */
+'CHECK'
+/** The server answered with a bundle for this device — the offer, before any bytes move. */
+ | 'OFFERED' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_PROGRESS' | 'DOWNLOAD_COMPLETE'
+/** Staged and swapped. Emitted optimistically, BEFORE the bundle has booted. */
+ | 'INSTALLED'
+/** The bundle booted and survived to the healthy mark — the honest activation signal. */
+ | 'BOOT_SUCCESS' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK'
+/**
+ * The SDK refused to check for / install an update because the device reported
+ * root or jailbreak indicators and the host configured
+ * `ota.onCompromisedDevice: 'withhold'`.
+ *
+ * LOCAL-ONLY, on purpose — see the queueing rule in `emit()`. A host must
+ * never have to infer "we withheld an update" from an update that simply
+ * never arrived, so this is emitted even though nothing uploads it.
+ */
+ | 'UPDATE_WITHHELD';
+export interface OtaEvent {
+    type: OtaEventType;
+    bundleId: string;
+    /**
+     * The release this bundle was served as. Optional because a bundle installed
+     * by an older SDK has no recorded release; present on everything emitted by a
+     * current one, so the delivery funnel can key by release rather than bundle.
+     */
+    releaseId?: string;
+    version?: number;
+    /** 0–100 for DOWNLOAD_PROGRESS */
+    progress?: number;
+    /** Duration in ms for DOWNLOAD_COMPLETE */
+    durationMs?: number;
+    /** Error description for APPLY_FAILED */
+    error?: string;
+    /** Rollback reason for AUTO_ROLLBACK */
+    reason?: string;
+    /** Whether a patch was used for this download */
+    patchUsed?: boolean;
+    /**
+     * Root/jailbreak indicator strings for UPDATE_WITHHELD — the reasons the
+     * device was judged compromised, verbatim from the native detector
+     * (`DeviceIntegrity.kt` / `DeviceIntegrity.swift`). Never present on any other
+     * event type.
+     */
+    indicators?: string[];
+    /** Timestamp of the event */
+    timestamp: number;
+}
+export type OtaEventListener = (event: OtaEvent) => void;
+declare class OtaEventEmitterImpl {
+    private listeners;
+    private pendingEvents;
+    private flushCallback;
+    /**
+     * Subscribe to OTA lifecycle events.
+     * Returns an unsubscribe function.
+     */
+    addListener(listener: OtaEventListener): () => void;
+    /**
+     * Remove a specific listener.
+     */
+    removeListener(listener: OtaEventListener): void;
+    /**
+     * Emit an event to all listeners + queue for telemetry flush.
+     */
+    emit(event: OtaEvent): void;
+    /**
+     * Register a callback that receives batched events for telemetry upload.
+     * Called by the SDK core to wire into the existing batch transport.
+     */
+    setFlushCallback(cb: (events: OtaEvent[]) => void): void;
+    /**
+     * Flush pending events to the telemetry pipeline.
+     * Called periodically by the SDK's batch transport.
+     */
+    flush(): OtaEvent[];
+    /**
+     * Helper to emit a standard event with minimal boilerplate.
+     */
+    emitSimple(type: OtaEventType, bundleId: string, extra?: Partial<Omit<OtaEvent, 'type' | 'bundleId' | 'timestamp'>>): void;
+}
+/** Singleton — one event bus per app lifecycle. */
+export declare const otaEventEmitter: OtaEventEmitterImpl;
+export {};
+//# sourceMappingURL=OtaEventEmitter.d.ts.map