@scalebun/react-native 1.3.3 → 1.5.0

package/src/analytics/EventTracker.ts

@@ -19,7 +19,9 @@
  */
 
 import { createStorageBackend, StorageBackend } from '../storage/StorageBackend';
+import { resolveEventPlatform } from '../core/context/device';
 import { getDeviceId } from '../core/id/deviceId';
+import { SDK_VERSION } from '../core/constants/version';
 import { logger } from '../core/logger/internalLogger';
 import { setNativeActiveSession } from '../features/crash/nativeCrashBridge';
 import { hmacSha256Hex } from '../crypto/hmacSha256';
@@ -141,7 +143,7 @@ export class EventTracker {
     constructor(config: EventTrackerConfig) {
         this.storage = createStorageBackend();
         this.cfg = {
-            platform: 'react_native',
+            platform: resolveEventPlatform(),
             flushIntervalMs: DEFAULT_FLUSH_MS,
             batchSize: DEFAULT_BATCH,
             autoLifecycleEvents: true,
@@ -315,7 +317,27 @@ export class EventTracker {
         const effectiveBatch = clampBatchSize(this.cfg.batchSize, DEFAULT_BATCH);
         const batch = this.queue.slice(0, effectiveBatch);
         try {
-            // Sign the exact bytes we send so the backend can tamper-detect the payload.
+            // WHAT THIS SIGNATURE IS, AND WHAT IT IS NOT.
+            //
+            // This used to be described as letting "the backend tamper-detect
+            // the payload", which overstates it to the point of being wrong.
+            // The HMAC key is `clientKey` — the same value sent beside it in
+            // `x-scalebun-client-key`, and a value that ships inside every
+            // installed app, extractable by anyone who unzips an APK. A MAC
+            // whose key travels with the message and is public by construction
+            // proves nothing about who sent it: anyone can compute a valid one.
+            //
+            // What it DOES buy is integrity in transit against non-adversarial
+            // corruption, and a cheap filter for junk traffic. Treat `clientKey`
+            // as a publishable identifier (like a Stripe publishable key), never
+            // as a trust boundary. Authenticity that actually holds has to come
+            // from something the client cannot forge — server-side rate limits
+            // and anomaly detection per key, short-lived device tokens, or
+            // platform attestation (Play Integrity / App Attest).
+            //
+            // Contrast with OTA bundle signing (features/ota/signature.ts),
+            // which is asymmetric: the private half never leaves the publisher,
+            // so a valid signature there IS proof of origin.
             const payload = JSON.stringify({ events: batch });
             // Wave 2 (§2F.2): a stable idempotency key over the batch's event ids so a
             // retry after a timeout/disconnect replays the first response instead of
@@ -380,14 +402,14 @@ export class EventTracker {
             event_name: eventName,
             event_time: Date.now(),
             app_id: this.cfg.appId,
-            platform: this.cfg.platform ?? 'react_native',
+            platform: this.cfg.platform ?? resolveEventPlatform(),
             installation_id: this.installationId,
             anonymous_id: this.anonymousId,
             session_id: canonicalSessionId || this.sessionId,
             device_id: getDeviceId(),
             // Phase 4: experiment stamps ride on every event; explicit props override.
             properties: { ...this.stamps, ...(properties ?? {}) },
-            context: { sdk_version: ctx.sdk_version ?? '0.1.0', ...ctx },
+            context: { sdk_version: ctx.sdk_version ?? SDK_VERSION, ...ctx },
         };
         if (this.userId) env.user_id = this.userId;
         if (this.cfg.appVersion) env.app_version = this.cfg.appVersion;

package/src/analytics/eventLane.ts

@@ -24,3 +24,25 @@ export function isSessionLaneEvent(name: string): boolean {
 export function resolveEventLane(name: string): EventLane {
     return isSessionLaneEvent(name) ? 'session' : 'analytics';
 }
+
+/**
+ * Signals that stay IN-PROCESS: they fan out to the engage trigger engine, the perf collectors and
+ * the desktop debug stream, but are NOT uploaded as session events — because each one already has
+ * its own dedicated ingestion lane carrying strictly more data.
+ *
+ * `$network_request` is the founding member: NetworkFeature writes every request to the
+ * `network_requests` table via reportNetworkRequest (method/status/timing/sizes/headers), and ALSO
+ * tracked it — which uploaded a second copy as a USER_ACTION session event that nothing reads. The
+ * dashboard's inspector explicitly filters that echo out as noise, the heatmap route catalog
+ * documents it as pollution, and measured sessions carried ~15% of their event volume in it.
+ * (`$perf_event` was the same pattern, removed at its emit site — d81e0ab.)
+ *
+ * Rule for adding here: the signal must have a dedicated lane that every consumer reads. A signal
+ * whose ONLY record is the session event stream must never be added.
+ */
+const INTERNAL_ONLY_SIGNALS = new Set(['$network_request']);
+
+/** Should this tracked event be uploaded to the session-events lane at all? */
+export function isUploadedSessionEvent(name: string): boolean {
+    return !INTERNAL_ONLY_SIGNALS.has(name);
+}

package/src/core/constants/version.ts

@@ -3,4 +3,4 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export const SDK_VERSION = '1.3.3';
+export const SDK_VERSION = '1.5.0';

package/src/core/context/device.ts

@@ -144,3 +144,20 @@ export function mergeDeviceContext(
 ): Record<string, unknown> {
     return { ...(configured ?? {}), ...detected };
 }
+
+/**
+ * The analytics envelope lane's platform value, AUTO-DETECTED.
+ *
+ * The init config's `platform` field was documented as "Default: react_native" — so every
+ * integration that did not hand-write `platform: 'ios' | 'android'` stamped the literal
+ * `react_native` on all its analytics events, and the dashboard's platform filters (which split
+ * ios/android) silently excluded them. Asking the developer for a value the runtime knows is an
+ * integration tax with a failure mode; `Platform.OS` answers it exactly.
+ *
+ * `react_native` remains only for the genuinely-unknown case (RN unloadable, or an OS the wire
+ * enum does not carry) — an honest "RN, platform untold" rather than a confident wrong answer.
+ */
+export function resolveEventPlatform(): 'ios' | 'android' | 'web' | 'react_native' {
+    const os = resolvePlatformOS();
+    return os === 'ios' || os === 'android' || os === 'web' ? os : 'react_native';
+}

package/src/core/id/installationId.ts

@@ -0,0 +1,52 @@
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
+
+/**
+ * The SDK's canonical per-install id.
+ *
+ * ONE install, ONE id, every lane. This is deliberately NOT `getDeviceId()` —
+ * that is a separate value under a separate storage key, and the backend schema
+ * annotates the two as different ("stable per-install id from the SDK (≠
+ * deviceId)").
+ *
+ * It matters because the backend joins a bundle's OTA installs to that device's
+ * sessions through this value. OTA events have always been keyed by it; the
+ * session lane did not send it at all, so on the server the two could only be
+ * connected for devices that happened to have registered for push. Release
+ * health then reported "no data" for bundles that were running perfectly well —
+ * or crashing badly.
+ *
+ * Lives here rather than inside one feature so the OTA orchestrator and the
+ * session adapter cannot drift to two different ids.
+ */
+export function resolveInstallationId(): string {
+    try {
+        const storage = createStorageBackend();
+        const existing = storage.get(K_INSTALLATION_ID);
+        if (existing) return existing;
+        const id = `inst-${randomSegment()}${randomSegment()}`;
+        storage.set(K_INSTALLATION_ID, id);
+        return id;
+    } catch {
+        // Storage unavailable (tests, exotic hosts): a per-process id keeps the
+        // lanes functional; it stabilizes on the first run where storage works.
+        return `inst-ephemeral-${randomSegment()}`;
+    }
+}
+
+/** 8 chars of base36 entropy, crypto-backed when the runtime offers it. */
+function randomSegment(): string {
+    try {
+        const g = globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => Uint8Array } };
+        if (g.crypto?.getRandomValues) {
+            const bytes = g.crypto.getRandomValues(new Uint8Array(6));
+            return Array.from(bytes)
+                .map((b) => b.toString(36).padStart(2, '0'))
+                .join('')
+                .slice(0, 8);
+        }
+    } catch {
+        // fall through to Math.random
+    }
+    return Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+}

package/src/debug/bootstrap.ts

@@ -16,6 +16,7 @@
 
 import { DebugTransport, type DebugTransportConfig } from './transport';
 import { DEFAULT_WS_PORT, DEBUG_READY_EMIT_DELAY_MS } from '../core/constants/timings';
+import { SDK_VERSION } from '../core/constants/version';
 import { DebugEventStream } from './stream';
 import { CommandRegistry } from './commands';
 import { PerfMonitor } from './perf';
@@ -66,6 +67,24 @@ export interface DebugConfig {
     /** @internal */
     _performanceDisabled?: boolean;
     enableProfiler?: boolean;
+    /**
+     * Permit the debug channel in a RELEASE build. Default false, and you
+     * almost certainly want it that way.
+     *
+     * The transport is an unencrypted `ws://` socket that carries captured
+     * console output, network traffic and the shared `secret` itself in
+     * cleartext, readable by anyone on the same Wi-Fi. That is an acceptable
+     * trade for a developer on their own machine and not acceptable in an app
+     * on a user's phone.
+     *
+     * Until now the only thing standing between those two cases was that the
+     * desktop tooling is excluded from bundles by default — a BUILD-time
+     * opt-out, not a release check. Anyone who set `devTools: true` to debug
+     * locally and shipped without reverting it published an app that opens
+     * that socket in production. This flag makes that a deliberate act rather
+     * than an oversight.
+     */
+    allowInRelease?: boolean;
 }
 
 // ─── Singleton State ────────────────────────────────────────────────────────
@@ -114,6 +133,24 @@ export function enableDebug(config: DebugConfig): void {
             return;
         }
 
+        // Refuse in release builds. See `allowInRelease` on DebugConfig: this
+        // channel is plaintext ws:// carrying console output, network traffic
+        // and the shared secret, and the only previous guard was that the
+        // tooling is excluded from bundles by default — which a developer
+        // disables to debug locally and then forgets. Warn rather than fail
+        // silently, because a debug connection that does nothing with no
+        // explanation is its own long afternoon.
+        if (!__DEV__ && !config.allowInRelease) {
+            logger.warn(
+                '[ScaleBun] Debug connection refused in a release build. The debug ' +
+                    'transport is unencrypted (ws://) and carries captured traffic and the ' +
+                    'shared secret in cleartext, so it is development-only by default. If ' +
+                    'you genuinely need it in a release build, set ' +
+                    '`allowInRelease: true` — and do not ship that to users.',
+            );
+            return;
+        }
+
         // The desktop-debugger tooling can be excluded from a build via
         // `withScaleBun(config, { features: { devTools: false } })`, which resolves these modules
         // to an empty stub. Detect that explicitly: without this check the first `new
@@ -262,7 +299,7 @@ export function enableDebug(config: DebugConfig): void {
                     journeyEnabled: _journeyConfig.enabled,
                     canScreenshot: true,
                     navMode: _autoScreenDetector ? 'auto' : 'beacon',
-                    sdkVersion: '1.0.0',
+                    sdkVersion: SDK_VERSION,
                 });
                 __DEV__ && logger.debug('Emitted journey:debug_ready event to desktop');
             } catch { /* no-throw */ }

package/src/debug/transport.ts

@@ -30,6 +30,7 @@ import {
     TRANSPORT_RECONNECT_MAX_MS,
     TRANSPORT_HIGH_LATENCY_WARN_MS,
 } from '../core/constants/timings';
+import { SDK_VERSION } from '../core/constants/version';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -272,7 +273,7 @@ export class DebugTransport {
             timestamp: Date.now(),
             sequence: this.nextSequence(),
             payload: {
-                sdkVersion: '0.1.0',
+                sdkVersion: SDK_VERSION,
                 appName: this.config.appName,
                 appVersion: this.config.appVersion,
                 bundleId: this.config.bundleId,

package/src/features/journey/journeyManager.ts

@@ -17,6 +17,7 @@ import type {
 } from './journeyTypes';
 import { DEFAULT_JOURNEY_CONFIG } from './journeyTypes';
 import { GestureBuffer } from './gestureBuffer';
+import { SDK_VERSION } from '../../core/constants/version';
 import { GestureDetector } from './gestureDetector';
 import { NavDetector } from './navDetector';
 import { ScreenshotHelper } from './screenshotHelper';
@@ -435,7 +436,7 @@ export class JourneyManager {
             journeyEnabled: this.config.enabled,
             canScreenshot: this.screenshotHelper.canCapture,
             navMode: this.navDetector.navMode,
-            sdkVersion: '0.1.0',
+            sdkVersion: SDK_VERSION,
         };
         this._emitEvent(JOURNEY_EVENTS.DEBUG_READY, payload as unknown as Record<string, unknown>);
     }

package/src/features/ota/OtaOrchestrator.ts

@@ -13,7 +13,7 @@ import type { OtaCheckRequest, OtaCheckResponse, OtaBundlePayload } from './OtaT
 import { otaEventEmitter } from './OtaEventEmitter';
 import { getDeviceCountry, prefetchDeviceCountry } from './geoCountry';
 import { deviceTargetingAttributes } from './deviceAttributes';
-import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
+import { resolveInstallationId } from '../../core/id/installationId';
 import { verifyBundleSignature, type SignatureConfig } from './signature';
 import { detectOtaEnvironment, type OtaEnvironment } from './environment';
 import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
@@ -71,35 +71,6 @@ function subscribeNativeProgress(
 /** POST at most once per this interval; first and terminal ticks always go. */
 const PROGRESS_POST_INTERVAL_MS = 1_000;
 
-/**
- * P8 — the SDK's canonical per-install id, shared with the analytics lane.
- *
- * OTA used to REQUIRE a caller-supplied `installationId`, and the documented
- * example passed `deviceId` — so OTA telemetry lived in its own identity
- * namespace, disconnected from the id every other lane reports. Every join
- * from OTA data to CDP data (blast radius, MRR-at-risk, churn bands) was a
- * cross-namespace join that matched by luck.
- *
- * Reads (or mints, for OTA-only apps that never initialize analytics) the same
- * persisted value `EventTracker` uses, via the same storage backend and the
- * same exported key — one install, one id, every lane.
- */
-function resolveInstallationId(): string {
-  try {
-    const storage = createStorageBackend();
-    const existing = storage.get(K_INSTALLATION_ID);
-    if (existing) return existing;
-    const id = `inst-${Math.random().toString(36).slice(2, 10)}${Math.random()
-      .toString(36)
-      .slice(2, 10)}`;
-    storage.set(K_INSTALLATION_ID, id);
-    return id;
-  } catch {
-    // Storage unavailable (tests, exotic hosts): a per-process id keeps sync
-    // functional; it will stabilize on the first run where storage works.
-    return `inst-ephemeral-${Math.random().toString(36).slice(2, 10)}`;
-  }
-}
 
 /**
  * Deliver queued OTA lifecycle events to the backend's batch endpoint.

package/src/features/performance/collectors/FrameMetricsCollector.ts

@@ -29,6 +29,21 @@ export class FrameMetricsCollector {
     private appStateSubscription: NativeEventSubscription | null = null;
     /** True while the native sampler is actually running (i.e. armed AND foregrounded). */
     private sampling = false;
+    /** Timestamp of the last emitted window — drives the healthy-window heartbeat below. */
+    private lastEmitTs = 0;
+
+    /**
+     * HEALTHY windows emit at a heartbeat, not per report interval.
+     *
+     * The native sampler reports every `reportIntervalMs` (5 s), and every window became a stored
+     * row — on a session hours long that is 720 rows/hour of "still 60 fps", which is how real
+     * sessions hit the dashboard's 2,000-row display cap with nothing to say. A window that shows
+     * ANY jank (dropped/frozen frames, meaningful slow-frame count, an FPS dip) always emits; a
+     * healthy window emits only when the heartbeat has elapsed, keeping the FPS series alive for
+     * the charts at 1/12th the volume. Capture cadence is unchanged — only identical-looking
+     * healthy rows are elided, and the first window after ANY emit gap states the recovery.
+     */
+    private static readonly HEALTHY_HEARTBEAT_MS = 60_000;
 
     constructor(
         config: PerformanceConfig,
@@ -161,10 +176,24 @@ export class FrameMetricsCollector {
             ? Math.round((actualFrames / expectedFrames) * 60)
             : 60;
 
+        const clampedFps = Math.min(60, Math.max(0, estimatedFps));
+
+        // Healthy-window heartbeat — see HEALTHY_HEARTBEAT_MS. Jank always emits.
+        const now = Date.now();
+        const healthy =
+            droppedFrames === 0 &&
+            frozenFrames === 0 &&
+            slowFrames <= 2 &&
+            clampedFps >= 55;
+        if (healthy && this.lastEmitTs !== 0 && now - this.lastEmitTs < FrameMetricsCollector.HEALTHY_HEARTBEAT_MS) {
+            return;
+        }
+        this.lastEmitTs = now;
+
         const event: FrameMetricsEvent = {
-            id: `frames-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+            id: `frames-${now}-${Math.random().toString(36).substring(2, 8)}`,
             type: 'frame_metrics',
-            timestamp: Date.now(),
+            timestamp: now,
             schemaVersion: PERF_SCHEMA_VERSION,
             context: this.contextProvider(),
             windowMs,
@@ -172,7 +201,7 @@ export class FrameMetricsCollector {
             droppedFrames,
             slowFrames,
             frozenFrames,
-            estimatedFps: Math.min(60, Math.max(0, estimatedFps)),
+            estimatedFps: clampedFps,
             maxFrameTimeMs,
         };
 

package/src/features/performance/collectors/JsStallCollector.ts

@@ -37,6 +37,11 @@ export class JsStallCollector {
     private maxStallMs = 0;
     private totalStallMs = 0;
     private recentStalls: Array<{ timestamp: number; durationMs: number }> = [];
+    /** Per-run caps on INDIVIDUAL stall events — see the emit site. Summaries are uncapped. */
+    private static readonly EMITTED_STALLS_MAX = 200;
+    private static readonly CRITICAL_OVERFLOW_MAX = 100;
+    private emittedStalls = 0;
+    private emittedCriticalOverflow = 0;
 
     constructor(
         config: PerformanceConfig,
@@ -121,9 +126,23 @@ export class JsStallCollector {
             this.recentStalls = this.recentStalls.slice(-MAX_STALL_RECORDS / 2);
         }
 
-        // Emit individual stall events for severe stalls (>100ms)
+        // Emit individual stall events for severe stalls (>100ms) — per-run capped.
+        //
+        // On a chronically janky device this fired per stall for the whole session: hours of the
+        // same diagnosis, thousands of rows, and the session's perf tab pinned at its display cap.
+        // The first EMITTED_STALLS_MAX stalls carry the individual detail; after that only
+        // criticals (>500 ms) still emit, themselves capped, and everything keeps counting into
+        // the periodic summary (stallCount/maxStallMs/totalStallMs) so no stall goes unmeasured —
+        // only the thousandth copy of the same story goes unshipped.
         if (durationMs > 100) {
             const severity = this._classifySeverity(durationMs);
+            if (this.emittedStalls >= JsStallCollector.EMITTED_STALLS_MAX) {
+                if (severity !== 'critical') return;
+                if (this.emittedCriticalOverflow >= JsStallCollector.CRITICAL_OVERFLOW_MAX) return;
+                this.emittedCriticalOverflow++;
+            } else {
+                this.emittedStalls++;
+            }
             const event: JsStallEvent = {
                 id: `stall-${timestamp}-${Math.random().toString(36).substring(2, 8)}`,
                 type: 'js_stall',

package/src/features/session/BackendSessionAdapter.ts

@@ -26,6 +26,7 @@
 import { logger } from '../../core/logger/internalLogger';
 import { base64ToBytes } from '../../core/encoding/base64';
 import { ENDPOINTS } from '../../transport/http/endpoints';
+import { resolveInstallationId } from '../../core/id/installationId';
 import { SDK_VERSION } from '../../core/constants/version';
 import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { getReplaySdkNative } from '../replay/bridge/nativeModule';
@@ -262,6 +263,13 @@ export class BackendSessionAdapter implements SessionTransport {
                 const payload = {
                     sessionId: session.sessionId,
                     deviceId: session.deviceId,
+                    // The canonical per-install id — the SAME value OTA events are
+                    // reported under, and a DIFFERENT value from deviceId. The
+                    // backend stores it on the Device so release health can join a
+                    // bundle's installs to that device's sessions. Without it, crash
+                    // impact for a release resolves to "no data" for every device
+                    // that never registered for push.
+                    installationId: resolveInstallationId(),
                     startedAt: session.startedAt,
                     // Link the recording row to the always-on analytics row so the
                     // dashboard can join them. track() events land on the analytics

package/src/public/ScaleBunFacade.ts

@@ -20,7 +20,7 @@ import { PersistentQueue } from '../pipeline/queue/persistentQueue';
 import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
 import { HttpClient } from '../transport/http/httpClient';
 import { getDeviceId } from '../core/id/deviceId';
-import { mergeDeviceContext } from '../core/context/device';
+import { mergeDeviceContext, resolveEventPlatform } from '../core/context/device';
 import { coreContainer } from '../core/di/container';
 import { flushQueue } from '../pipeline/queue/flushQueue';
 import {
@@ -52,7 +52,7 @@ import {
     emitAutomaticEvent,
     type AutomaticEventName,
 } from '../analytics/automaticEvents';
-import { resolveEventLane } from '../analytics/eventLane';
+import { resolveEventLane, isUploadedSessionEvent } from '../analytics/eventLane';
 import { ConfigManager } from '../config/ConfigManager';
 import { SDK_VERSION } from '../core/constants/version';
 import { EngageTransport, type SubmitStage } from '../features/engage/EngageTransport';
@@ -347,7 +347,8 @@ class ScaleBunFacade {
                 appId,
                 clientKey,
                 apiBaseUrl,
-                platform: rawConfig?.platform ?? 'react_native',
+                // Auto-detected (Platform.OS) unless the integration overrides it — see resolveEventPlatform.
+                platform: rawConfig?.platform ?? resolveEventPlatform(),
                 appVersion: rawConfig?.appVersion,
                 osVersion: rawConfig?.osVersion,
                 autoLifecycleEvents: rawConfig?.autoLifecycleEvents !== false,
@@ -1224,7 +1225,14 @@ class ScaleBunFacade {
             engageSignals.emit(name, payload);
 
             const adapter = SessionManager.getExistingInstance()?.getBackendTransport();
-            if (this._clientKey && adapter) {
+            // Internal-only signals ($network_request, …) fan out to engage/perf/debug below but
+            // are never uploaded as session events — their data already travels on a dedicated
+            // lane (see INTERNAL_ONLY_SIGNALS in analytics/eventLane). The uploaded copy was pure
+            // duplication: ~15% of measured mobile event volume, filtered out as noise by every
+            // dashboard reader.
+            if (!isUploadedSessionEvent(name)) {
+                // fall through to the in-process consumers
+            } else if (this._clientKey && adapter) {
                 // SaaS mode → always-on analytics ingestion lane (NOT /sdk/events).
                 // sessionId is stamped by the lane at flush time, so the call-time
                 // value is a placeholder; endpoint id == body sessionId by construction.

package/src/public/types.ts

@@ -334,7 +334,7 @@ export interface SimplifiedInitConfig {
     appId?: string;
     /** SDK client key (SaaS mode). Also used to authenticate the envelope lane. */
     clientKey?: string;
-    /** Platform override: ios | android | web | react_native. Default: react_native. */
+    /** Platform OVERRIDE — auto-detected from Platform.OS when omitted (integrations should omit it). */
     platform?: 'ios' | 'android' | 'web' | 'react_native';
     /**
      * Enable the Phase 1 envelope tracking lane (first_open/app_open/session_start/