@scalebun-release/react-native 2.5.0

package/lib/module/features/network/NetworkFeature.js

@@ -0,0 +1,209 @@
+/**
+ * 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 { installNetworkMonitoring } from './index';
+import { isAppRequest } from './thirdParty';
+import { reportNetworkRequest } from '../replay/integrations/network/networkAdapter';
+import { SessionManager } from '../session/SessionManager';
+import { getTrackedScreen } from '../../debug/screenTracking';
+import { quotaState } from '../../config/quotaState';
+
+/**
+ * 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 function serializeNetworkBody(body) {
+  if (body === undefined || body === null) return undefined;
+  if (typeof body === 'string') return body;
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return String(body);
+  }
+}
+export class NetworkFeature {
+  name = 'network';
+  active = false;
+  constructor(trackFn, options = {}) {
+    this.trackFn = trackFn;
+    this.options = options;
+  }
+  initialize(_context) {
+    if (this.active) return;
+    installNetworkMonitoring(data => {
+      // The SDK's own telemetry uploads are themselves network requests.
+      // Feeding them to track('$network_request') → PerformanceFeature
+      // .processNetworkEvent → NetworkPerfCollector turns every upload into
+      // a network_perf event, which queues another upload → an unbounded
+      // self-capture loop. Apply the SAME isSdkInternalUrl filter the replay
+      // branch below already uses so genuine app requests still flow through.
+      const isInternal = isSdkInternalUrl(data.url, this.options.sdkBaseUrl);
+      /**
+       * Beacons and denied URLs leave NO trace, in any lane.
+       *
+       * A network request reaches three places from here: the analytics echo
+       * (`$network_request`), the local replay pipeline, and the backend network endpoint
+       * that becomes the `network_requests` row the session panel renders. Filtering one
+       * and not the others is how a request half-disappears and two counts of the same
+       * call stop agreeing -- so this is applied to all three.
+       *
+       * Kept separate from `isInternal` rather than folded into it: the SDK's own uploads
+       * are already excluded from two of the three lanes and DELIBERATELY still reach the
+       * local replay pipeline. Widening that here would be an unrelated behaviour change
+       * riding along on a filter.
+       */
+      const isBeaconOrDenied = this.options.captureThirdParty !== true && !isAppRequest(data.url, undefined, this.options.thirdPartyHosts) || matchesDenyUrl(data.url, this.options.denyUrls);
+      const isExcluded = isInternal || isBeaconOrDenied;
+      if (!isExcluded) {
+        this.trackFn('$network_request', data);
+      }
+
+      // Bridge the raw network event into the Session Replay pipeline
+      if (data.type === 'network' && !isBeaconOrDenied) {
+        reportNetworkRequest({
+          method: data.method,
+          url: data.url,
+          statusCode: data.status,
+          durationMs: data.duration,
+          requestSizeBytes: data.requestBody ? JSON.stringify(data.requestBody).length : 0,
+          responseSizeBytes: data.responseBody ? typeof data.responseBody === 'string' ? data.responseBody.length : JSON.stringify(data.responseBody).length : 0,
+          error: data.status === 0 || !!data.error,
+          errorMessage: data.error,
+          startTimestamp: Date.now() - data.duration,
+          requestHeaders: data.requestHeaders,
+          responseHeaders: data.responseHeaders,
+          requestBody: data.requestBody,
+          responseBody: data.responseBody
+        });
+
+        // Forward network event to the SaaS backend dedicated network
+        // endpoint — the SINGLE source of truth for network activity.
+        // The replay timeline derives network markers from network_requests
+        // (correlated by sessionId+timestamp), so we no longer emit
+        // NETWORK_REQUEST_* replay events here (that produced duplicate rows
+        // and count divergence between replay_events and network_requests).
+        // Skip SDK's own upload calls to prevent recursive event spam, and anything the
+        // beacon/denyUrls filter excluded -- this is the lane that becomes the
+        // network_requests row a person sees on the session panel.
+        // Quota (contract v1): the interceptor cannot be uninstalled, so a `networkRequests`
+        // block is a gate here — nothing is serialized or queued for a row that would be refused.
+        // The app's own request is untouched; only the SDK's record of it is skipped.
+        if (!isExcluded && !quotaState.isBlocked('networkRequests')) {
+          const sessionManager = SessionManager.getExistingInstance();
+          if (sessionManager) {
+            const backendTransport = sessionManager.getBackendTransport();
+            if (backendTransport) {
+              backendTransport.queueNetworkRequest({
+                method: data.method ?? 'GET',
+                url: data.url,
+                statusCode: typeof data.status === 'number' ? data.status : undefined,
+                duration: typeof data.duration === 'number' ? data.duration : undefined,
+                error: data.error ? String(data.error) : undefined,
+                requestSize: typeof data.requestSize === 'number' ? data.requestSize : undefined,
+                responseSize: typeof data.responseSize === 'number' ? data.responseSize : undefined,
+                screenName: getTrackedScreen() ?? undefined,
+                requestHeaders: data.requestHeaders,
+                responseHeaders: data.responseHeaders,
+                requestBody: serializeNetworkBody(data.requestBody),
+                responseBody: serializeNetworkBody(data.responseBody)
+              });
+            }
+          }
+        }
+      }
+    }, {
+      ...this.options,
+      /**
+       * ── IS THE APP STILL WAITING? ────────────────────────────────────────────────────
+       *
+       * Replay capture uses this to hold a frame until the screen has its data, instead of
+       * photographing the skeleton and then never photographing the result. It asks one
+       * question — are there requests outstanding — so it gets a counter, not a record.
+       *
+       * THE SDK'S OWN TRAFFIC MUST NOT COUNT. This SDK uploads frames, and a frame upload
+       * is triggered by a capture, which is triggered by a tap. Counting it would mean the
+       * app looks busy immediately after every interaction, and every subsequent capture
+       * would wait out the cap — the SDK holding itself up with its own exhaust. Beacons
+       * and denied URLs are excluded for the same reason they are excluded everywhere
+       * else: they are not the app, and an analytics pixel that hangs is not this screen
+       * failing to load.
+       *
+       * Both phases run through the SAME predicate on the SAME url, so a request is either
+       * counted at both ends or at neither. A filter that admitted one end would corrupt
+       * the count permanently, since nothing ever re-syncs it.
+       */
+      onRequestPhase: (phase, url) => {
+        if (isSdkInternalUrl(url, this.options.sdkBaseUrl)) return;
+        if (this.options.captureThirdParty !== true && !isAppRequest(url, undefined, this.options.thirdPartyHosts)) return;
+        if (matchesDenyUrl(url, this.options.denyUrls)) return;
+        SessionManager.getExistingInstance()?.onNetworkActivity(phase);
+      }
+    });
+    this.active = true;
+  }
+  teardown() {
+    // Network interceptors are process-global — cannot safely uninstall.
+    // Mark as inactive for feature registry tracking.
+    this.active = false;
+  }
+  get isActive() {
+    return this.active;
+  }
+}
+
+/**
+ * Substring or RegExp, the same rule as the web SDK's `matchUrl`.
+ *
+ * Spelled out rather than shared because the two SDKs have no common runtime package, and the
+ * rule is two lines. What must NOT differ is the beacon list, which is why that one is a
+ * byte-identical vendored copy with a hash gate rather than a retyped constant.
+ */
+function matchesDenyUrl(url, patterns) {
+  if (!patterns || !patterns.length || !url) return false;
+  for (const p of patterns) {
+    if (typeof p === 'string' ? url.includes(p) : p.test(url)) return true;
+  }
+  return false;
+}
+
+// Returns true if the URL is a ScaleBun SDK internal endpoint that must not be
+// captured — doing so would cause recursive network event spam.
+function isSdkInternalUrl(url, sdkBaseUrl) {
+  if (!url) return false;
+  try {
+    // Block by SDK base URL prefix when provided
+    if (sdkBaseUrl) {
+      const base = sdkBaseUrl.endsWith('/') ? sdkBaseUrl : sdkBaseUrl + '/';
+      if (url.startsWith(base) || url.startsWith(sdkBaseUrl)) return true;
+    }
+    // Block known ScaleBun replay path patterns regardless of host
+    const SDK_PATHS = ['/replay/sessions', '/api/v1/replay', '/api/replay', '/api/v1/ingestion', '/ingestion/sessions'];
+    return SDK_PATHS.some(p => url.includes(p));
+  } catch {
+    return false;
+  }
+}
+//# sourceMappingURL=NetworkFeature.js.map

package/lib/module/features/network/index.js

@@ -0,0 +1,17 @@
+/**
+ * ScaleBun SDK — Network Monitoring Entry Point
+ *
+ * Installs both XHR and fetch interceptors.
+ * Accepts network capture options so callers can opt in to body capture.
+ */
+
+import { installXHRInterceptor } from '../../integrations/xhr/xhrInterceptor';
+import { installFetchInterceptor } from '../../integrations/fetch/fetchInterceptor';
+import { noThrow } from '../../core/lifecycle/crashSafe';
+export function installNetworkMonitoring(onEvent, options = {}) {
+  noThrow(() => {
+    installXHRInterceptor(onEvent, options);
+    installFetchInterceptor(onEvent, options);
+  });
+}
+//# sourceMappingURL=index.js.map

package/lib/module/features/network/thirdParty.js

@@ -0,0 +1,142 @@
+/**
+ * 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 const THIRD_PARTY_BEACON_HOSTS = 'google-analytics.com,googletagmanager.com,analytics.google.com,doubleclick.net,googlesyndication.com,' + 'googleadservices.com,app-measurement.com,facebook.net,analytics.tiktok.com,' + 'ads-twitter.com,analytics.twitter.com,ct.pinterest.com,bat.bing.com,px.ads.linkedin.com,tr.snapchat.com,' +
+// Pixel delivery hosts seen leaking past the list on production (2026-09-22): Snapchat's pixel also
+// posts to tr6 / tr-shadow, TikTok's to its US analytics hosts. Exact hosts, not the parent domains —
+// snapchat.com and tiktokw.us also serve things an app may legitimately call.
+'tr6.snapchat.com,tr-shadow.snapchat.com,analytics.tiktokw.us,analytics-ipv6.tiktokw.us,' + 'criteo.com,criteo.net,taboola.com,outbrain.com,adroll.com,adsrvr.org,quantserve.com,scorecardresearch.com,' + 'hotjar.com,hotjar.io,clarity.ms,fullstory.com,mouseflow.com,crazyegg.com,luckyorange.com,inspectlet.com,' + 'segment.io,mixpanel.com,amplitude.com,heap.io,heapanalytics.com,rudderstack.com,posthog.com,' + 'matomo.cloud,plausible.io,simpleanalytics.com,statcounter.com,' + 'appsflyer.com,adjust.com,branch.io,' + 'ipify.org,ipinfo.io,ipapi.co,ip-api.com,geolocation-db.com,cloudflareinsights.com,' + 'nr-data.net,browser-intake-datadoghq.com,sentry.io,bugsnag.com,rollbar.com';
+
+/**
+ * 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 function isThirdPartyBeacon(url, hosts) {
+  // A relative URL has no host, which is the answer we want: it is first-party.
+  const host = parts(url)[1];
+  if (!host) return false;
+  for (const suffix of (hosts ?? THIRD_PARTY_BEACON_HOSTS).split(',')) {
+    // Dot boundary, so `notevil-facebook.com` does not match `facebook.com` while
+    // `connect.facebook.com` does. The bare-equality arm covers the apex domain itself.
+    if (host === suffix || host.endsWith('.' + suffix)) return true;
+  }
+  return false;
+}
+
+/**
+ * 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 function requestKind(url, protocol, hosts) {
+  const [scheme,, p, q] = parts(url);
+  if (scheme && !/^(https?|wss?)$/.test(scheme)) return 'other';
+  if (protocol === 'beacon' || p === '/cdn-cgi/rum' || p.endsWith('/generate_204') || isThirdPartyBeacon(url, hosts)) {
+    return 'telemetry';
+  }
+  if (/[?&](_rsc(=|&|$)|_data=(routes|root))/.test(q) || /\/(_next\/data\/.+|__data|_payload|page-data\/.+)\.json$/.test(p)) {
+    return 'page';
+  }
+  if (/\.(png|jpe?g|gif|svg|webp|avif|ico|bmp|woff2?|ttf|otf|eot|css|m?js|map|mp4|webm|mov|m3u8|mp3|m4a|wav|ogg)$/i.test(p)) {
+    return 'asset';
+  }
+  return 'api';
+}
+
+/**
+ * [scheme, host, path, query] of a URL, lower-cased where case is not significant.
+ *
+ * A regex, NOT `new URL`: React Native's built-in URL throws "not implemented" for hostname,
+ * pathname and searchParams, so the `new URL(url).hostname` this module used to call was caught
+ * and answered "first-party" for EVERY request on mobile — the host list silently never matched
+ * there. The same string parsing now runs identically in the browser, in React Native and in Node.
+ * Never throws; a string it cannot read yields empty parts, which classify as the app's own call.
+ */
+function parts(url) {
+  const m = /^(?:([a-z][\w+.-]*):)?(?:\/\/(?:[^@/?#]*@)?([^:/?#]*)[^/?#]*)?([^?#]*)(\?[^#]*)?/i.exec(url || '') || [];
+  return [(m[1] || '').toLowerCase(), (m[2] || '').toLowerCase(), m[3] || '', m[4] || ''];
+}
+
+/** True when the request is one of the app's own API calls — the only kind the network lane keeps. */
+export function isAppRequest(url, protocol, hosts) {
+  return requestKind(url, protocol, hosts) === 'api';
+}
+//# sourceMappingURL=thirdParty.js.map

package/lib/module/features/ota/OtaEventEmitter.js

@@ -0,0 +1,123 @@
+/**
+ * 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).
+ */
+
+// ── Event types ───────────────────────────────────────────────────────────────
+
+// ── Emitter ───────────────────────────────────────────────────────────────────
+
+class OtaEventEmitterImpl {
+  listeners = new Set();
+  pendingEvents = [];
+  flushCallback = null;
+
+  /**
+   * Subscribe to OTA lifecycle events.
+   * Returns an unsubscribe function.
+   */
+  addListener(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Remove a specific listener.
+   */
+  removeListener(listener) {
+    this.listeners.delete(listener);
+  }
+
+  /**
+   * Emit an event to all listeners + queue for telemetry flush.
+   */
+  emit(event) {
+    // Notify local listeners
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Never let a listener crash the OTA flow
+      }
+    }
+
+    // Queue for batch telemetry.
+    //
+    // DOWNLOAD_PROGRESS is deliberately NOT queued: too noisy, and it exists for
+    // the UI hook only.
+    //
+    // ── UPDATE_WITHHELD now uploads ──────────────────────────────────────────
+    //
+    // It used to be held back here because the backend's ingest lane validates
+    // `type` against a closed set and DROPS an unrecognised one silently, so
+    // queueing it would have spent a batch slot on a row discarded server-side
+    // and read downstream as "no device was ever withheld" rather than "the
+    // server refused the row".
+    //
+    // The backend now accepts it (`VALID_EVENT_TYPES` in
+    // ota-event-ingestion.service.ts), excludes it from the failure lists — a
+    // withheld device carries no errorCode and would otherwise normalise to an
+    // "unknown" failure — and keeps it out of the rollback types so it cannot
+    // move a guard.
+    //
+    // ⚠️ ORDERING: this half must not ship before that one. An SDK released
+    // against a backend that still has the old accept-list puts every withheld
+    // row straight back into the silent drop, and the symptom is indistinguishable
+    // from no device ever being withheld.
+    //
+    // The fleet-level question ("how much of my fleet is compromised?") is
+    // answered separately by `integrityIndicators` on the CHECK request. That
+    // field was ALSO being discarded — the backend's canonical OtaCheckRequest
+    // never declared it, so validation stripped it before any handler saw it.
+    // It is accepted and stored now. The claim once made here, that riding an
+    // existing accepted request meant no enumerating handler could drop it, was
+    // simply wrong: the contract itself was the enumerating handler.
+    if (event.type !== 'DOWNLOAD_PROGRESS') {
+      this.pendingEvents.push(event);
+    }
+  }
+
+  /**
+   * Register a callback that receives batched events for telemetry upload.
+   * Called by the SDK core to wire into the existing batch transport.
+   */
+  setFlushCallback(cb) {
+    this.flushCallback = cb;
+  }
+
+  /**
+   * Flush pending events to the telemetry pipeline.
+   * Called periodically by the SDK's batch transport.
+   */
+  flush() {
+    const events = [...this.pendingEvents];
+    this.pendingEvents = [];
+    if (events.length > 0 && this.flushCallback) {
+      try {
+        this.flushCallback(events);
+      } catch {
+        // best-effort
+      }
+    }
+    return events;
+  }
+
+  /**
+   * Helper to emit a standard event with minimal boilerplate.
+   */
+  emitSimple(type, bundleId, extra) {
+    this.emit({
+      type,
+      bundleId,
+      timestamp: Date.now(),
+      ...extra
+    });
+  }
+}
+
+/** Singleton — one event bus per app lifecycle. */
+export const otaEventEmitter = new OtaEventEmitterImpl();
+//# sourceMappingURL=OtaEventEmitter.js.map