@obsrviq/react-native 0.3.1

package/src/instrument/errors.ts

@@ -0,0 +1,28 @@
+import type { Emit } from '../emit';
+
+interface ErrorUtilsType {
+  getGlobalHandler(): ((error: unknown, isFatal?: boolean) => void) | undefined;
+  setGlobalHandler(cb: (error: unknown, isFatal?: boolean) => void): void;
+}
+
+/**
+ * Captures uncaught JS errors via RN's `global.ErrorUtils` (chaining the prior
+ * handler so we never swallow a crash). Emits `error` events. Pure JS.
+ */
+export function installErrors(emit: Emit): () => void {
+  const EU = (globalThis as unknown as { ErrorUtils?: ErrorUtilsType }).ErrorUtils;
+  if (!EU) return () => {};
+  const prev = EU.getGlobalHandler();
+  EU.setGlobalHandler((error, isFatal) => {
+    try {
+      const e = error instanceof Error ? error : new Error(String(error));
+      emit({ type: 'error', name: e.name, message: e.message, stack: e.stack, handled: false });
+    } catch {
+      /* never let instrumentation mask the real crash */
+    }
+    prev?.(error, isFatal);
+  });
+  return () => {
+    if (prev) EU.setGlobalHandler(prev);
+  };
+}

package/src/instrument/network.ts

@@ -0,0 +1,219 @@
+import type { Emit } from '../emit';
+
+export interface NetworkOptions {
+  /** The ingest batch URL — never record the SDK's own uploads (infinite loop). */
+  skipUrl: string;
+  captureBodies: boolean;
+  redactHeaders: string[];
+  /** relative `t` (ms since session start). */
+  now: () => number;
+}
+
+const BODY_CAP = 8 * 1024; // chars kept of a captured body preview
+
+const num = (h: Headers | undefined, k: string): number | undefined => {
+  const v = h?.get(k);
+  const n = v ? Number(v) : NaN;
+  return Number.isFinite(n) ? n : undefined;
+};
+
+function pickHeaders(h: Headers | undefined, redact: string[]): Record<string, string> | undefined {
+  if (!h) return undefined;
+  const out: Record<string, string> = {};
+  const deny = new Set(redact.map((x) => x.toLowerCase()));
+  h.forEach((value, key) => {
+    out[key] = deny.has(key.toLowerCase()) ? '[redacted]' : value;
+  });
+  return Object.keys(out).length ? out : undefined;
+}
+
+/** Coerce fetch/XHR header inputs (Headers | object | array) into a Headers. */
+function toHeaders(input: unknown): Headers | undefined {
+  if (input == null) return undefined;
+  try {
+    return new Headers(input as ConstructorParameters<typeof Headers>[0]);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Only capture textual bodies (JSON/text/xml/form) — never binary blobs. */
+function isTexty(ct: string | null | undefined): boolean {
+  if (!ct) return false;
+  return /json|text|xml|javascript|x-www-form-urlencoded|graphql/i.test(ct);
+}
+
+/** Best-effort stringify of a request body (strings pass through; others skipped). */
+function stringifyBody(body: unknown): string | undefined {
+  if (body == null) return undefined;
+  if (typeof body === 'string') return body;
+  // URLSearchParams / objects with a toString worth keeping; binary/FormData skipped.
+  if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) return body.toString();
+  return undefined;
+}
+
+interface BodyPreview { contentType?: string; preview?: string; truncated?: boolean; redacted?: boolean }
+function bodyPreview(text: string | undefined, contentType: string | undefined): BodyPreview | undefined {
+  if (text == null) return undefined;
+  const truncated = text.length > BODY_CAP;
+  return { contentType, preview: truncated ? text.slice(0, BODY_CAP) : text, truncated, redacted: false };
+}
+
+/**
+ * Instruments `fetch` and `XMLHttpRequest` to emit `network` events. Mirrors the web
+ * tracker's network capture: method/url/status/timing/sizes, request + response header
+ * allowlist with redaction, and — when `captureBodies` is on — size-capped textual
+ * request/response bodies. Self-skips the ingest endpoint so the SDK never records (and
+ * thus re-uploads) its own traffic. Pure JS — runs on the JS thread, off the native
+ * capture path entirely.
+ */
+export function installNetwork(emit: Emit, opts: NetworkOptions): () => void {
+  const g = globalThis as unknown as {
+    fetch: typeof fetch;
+    XMLHttpRequest: typeof XMLHttpRequest;
+  };
+  const origFetch = g.fetch;
+  const OrigXHR = g.XMLHttpRequest;
+  const skip = (url: string) => url.indexOf(opts.skipUrl) !== -1;
+
+  // ── fetch ──
+  g.fetch = function patchedFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : (input as Request).url;
+    const method = (init?.method || (input instanceof Request ? input.method : 'GET') || 'GET').toUpperCase();
+    if (skip(url)) return origFetch(input as RequestInfo, init);
+
+    const reqHeaders = pickHeaders(
+      toHeaders(init?.headers ?? (input instanceof Request ? input.headers : undefined)),
+      opts.redactHeaders,
+    );
+    const requestBody = opts.captureBodies ? bodyPreview(stringifyBody(init?.body), undefined) : undefined;
+    const startT = opts.now();
+
+    return origFetch(input as RequestInfo, init).then(
+      (res) => {
+        const endT = opts.now();
+        const ct = res.headers.get('content-type');
+        // Read a clone of the body WITHOUT delaying the response returned to the app:
+        // emit fires after the (detached) body read resolves.
+        const finalize = (responseBody?: BodyPreview) =>
+          emit({
+            type: 'network',
+            initiator: 'fetch',
+            method,
+            url,
+            status: res.status,
+            ok: res.ok,
+            responseSize: num(res.headers, 'content-length'),
+            timing: { startT, endT, duration: endT - startT },
+            requestHeaders: reqHeaders,
+            responseHeaders: pickHeaders(res.headers, opts.redactHeaders),
+            requestBody,
+            responseBody,
+          });
+        if (opts.captureBodies && isTexty(ct)) {
+          res.clone().text().then((t) => finalize(bodyPreview(t, ct || undefined))).catch(() => finalize(undefined));
+        } else {
+          finalize(undefined);
+        }
+        return res;
+      },
+      (err: unknown) => {
+        const endT = opts.now();
+        emit({
+          type: 'network',
+          initiator: 'fetch',
+          method,
+          url,
+          status: 0,
+          ok: false,
+          timing: { startT, endT, duration: endT - startT },
+          requestHeaders: reqHeaders,
+          requestBody,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+      },
+    );
+  } as typeof fetch;
+
+  // ── XMLHttpRequest ──
+  type Tracked = XMLHttpRequest & {
+    __lum?: { method: string; url: string; startT: number; reqHeaders: Record<string, string>; body?: string };
+  };
+  const origOpen = OrigXHR.prototype.open;
+  const origSend = OrigXHR.prototype.send;
+  const origSetHeader = OrigXHR.prototype.setRequestHeader;
+  const deny = new Set(opts.redactHeaders.map((x) => x.toLowerCase()));
+
+  OrigXHR.prototype.open = function open(
+    this: Tracked,
+    method: string,
+    url: string | URL,
+    ...rest: unknown[]
+  ) {
+    this.__lum = { method: (method || 'GET').toUpperCase(), url: String(url), startT: 0, reqHeaders: {} };
+    // @ts-expect-error variadic passthrough to the native impl
+    return origOpen.call(this, method, url, ...rest);
+  };
+
+  OrigXHR.prototype.setRequestHeader = function setRequestHeader(this: Tracked, name: string, value: string) {
+    const meta = this.__lum;
+    if (meta) meta.reqHeaders[name] = deny.has(name.toLowerCase()) ? '[redacted]' : value;
+    return origSetHeader.call(this, name, value);
+  };
+
+  // `body` is whatever the app passes to xhr.send(); we forward it untouched.
+  OrigXHR.prototype.send = function send(this: Tracked, body?: unknown) {
+    const meta = this.__lum;
+    if (meta && !skip(meta.url)) {
+      meta.startT = opts.now();
+      if (opts.captureBodies) meta.body = stringifyBody(body);
+      this.addEventListener('loadend', () => {
+        const endT = opts.now();
+        const ct = this.getResponseHeader('content-type');
+        let responseBody: BodyPreview | undefined;
+        if (opts.captureBodies && isTexty(ct)) {
+          try {
+            if (this.responseType === '' || this.responseType === 'text') {
+              responseBody = bodyPreview(this.responseText, ct || undefined);
+            }
+          } catch {
+            /* opaque / cross-origin — skip */
+          }
+        }
+        emit({
+          type: 'network',
+          initiator: 'xhr',
+          method: meta.method,
+          url: meta.url,
+          status: this.status,
+          ok: this.status >= 200 && this.status < 400,
+          timing: { startT: meta.startT, endT, duration: endT - meta.startT },
+          requestHeaders: Object.keys(meta.reqHeaders).length ? meta.reqHeaders : undefined,
+          responseHeaders: pickHeaders(toHeaders(parseRawHeaders(this.getAllResponseHeaders())), opts.redactHeaders),
+          requestBody: opts.captureBodies ? bodyPreview(meta.body, undefined) : undefined,
+          responseBody,
+        });
+      });
+    }
+    return origSend.call(this, body);
+  };
+
+  return () => {
+    g.fetch = origFetch;
+    OrigXHR.prototype.open = origOpen;
+    OrigXHR.prototype.send = origSend;
+    OrigXHR.prototype.setRequestHeader = origSetHeader;
+  };
+}
+
+/** Parse the raw `getAllResponseHeaders()` string into a header object. */
+function parseRawHeaders(raw: string | null): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const line of raw.trim().split(/[\r\n]+/)) {
+    const i = line.indexOf(':');
+    if (i > 0) out[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return out;
+}

package/src/session.ts

@@ -0,0 +1,108 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { uuid } from './util';
+
+const SESSION_KEY = 'lumera.session';
+const VISITOR_KEY = 'lumera.visitor';
+
+interface StoredSession {
+  id: string;
+  startedAt: number; // epoch ms
+  lastActivity: number; // epoch ms
+  seq: number; // next batch seq for the structured-event stream
+  userId?: string;
+}
+
+interface StoredVisitor {
+  id: string;
+  firstSeenAt: number;
+  visitCount: number;
+}
+
+export interface ResolvedSession {
+  id: string;
+  startedAt: number;
+  /** Next structured-event-stream seq (continued sessions resume their seq). */
+  seq: number;
+  resumed: boolean;
+  visitorId: string;
+  visitCount: number;
+  firstSeenAt: number;
+}
+
+function safeParse<T>(raw: string | null): T | null {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the session + visitor identity from AsyncStorage. Mirrors the web tracker's
+ * model: a persistent anonymous visitor (stable across launches → returning-visitor
+ * detection) and an optional same-app continuation window. A returning launch within
+ * `timeoutMs` resumes the prior session (and its seq) — unless a different known user
+ * is supplied (shared-device split), which forces a fresh session.
+ */
+export async function resolveSession(opts: {
+  continueSession: boolean;
+  timeoutMs: number;
+  userId?: string;
+  now?: number;
+}): Promise<ResolvedSession> {
+  const now = opts.now ?? Date.now();
+
+  // ── Visitor (persistent, anonymous) ──
+  let visitor = safeParse<StoredVisitor>(await AsyncStorage.getItem(VISITOR_KEY));
+  if (!visitor) {
+    visitor = { id: uuid(), firstSeenAt: now, visitCount: 0 };
+  }
+
+  // ── Session (optional continuation) ──
+  let session: StoredSession | null = null;
+  if (opts.continueSession) {
+    const prior = safeParse<StoredSession>(await AsyncStorage.getItem(SESSION_KEY));
+    const fresh = prior && now - prior.lastActivity < opts.timeoutMs;
+    const sameUser = !opts.userId || !prior?.userId || prior.userId === opts.userId;
+    if (prior && fresh && sameUser) session = prior;
+  }
+
+  const resumed = session != null;
+  if (!session) {
+    session = { id: uuid(), startedAt: now, lastActivity: now, seq: 0, userId: opts.userId };
+    visitor.visitCount += 1; // a brand-new session = a new visit
+  }
+  session.lastActivity = now;
+  if (opts.userId) session.userId = opts.userId;
+
+  await AsyncStorage.multiSet([
+    [SESSION_KEY, JSON.stringify(session)],
+    [VISITOR_KEY, JSON.stringify(visitor)],
+  ]);
+
+  return {
+    id: session.id,
+    startedAt: session.startedAt,
+    seq: session.seq,
+    resumed,
+    visitorId: visitor.id,
+    visitCount: visitor.visitCount,
+    firstSeenAt: visitor.firstSeenAt,
+  };
+}
+
+/** Persist the latest seq + activity so a continued launch resumes correctly. */
+export async function persistProgress(id: string, seq: number, userId?: string): Promise<void> {
+  const prior = safeParse<StoredSession>(await AsyncStorage.getItem(SESSION_KEY));
+  if (!prior || prior.id !== id) return; // a reset() already moved on — don't clobber
+  await AsyncStorage.setItem(
+    SESSION_KEY,
+    JSON.stringify({ ...prior, seq, lastActivity: Date.now(), userId: userId ?? prior.userId }),
+  );
+}
+
+/** reset() / logout: drop the continuation record so the next session can't resume this user. */
+export async function clearSession(): Promise<void> {
+  await AsyncStorage.removeItem(SESSION_KEY);
+}

package/src/spec/NativeLumeraReplay.ts

@@ -0,0 +1,70 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * The native screen-capture module (iOS Swift / Android Kotlin), exposed to JS as a
+ * New-Architecture TurboModule.
+ *
+ * DESIGN INVARIANT: the JS surface is start / stop / configure / mask only. The
+ * capture loop — UI-thread raster, off-main masking + JPEG encode + gzip + UPLOAD —
+ * lives entirely in native code and NEVER crosses this boundary. No pixel or frame
+ * buffer is ever marshalled through the bridge/JSI (that is the #1 source of jank in
+ * naive implementations). The native side uploads `screen` frames straight to the
+ * ingest endpoint using the same siteKey + sessionId the JS layer hands it at start().
+ */
+
+export interface StartOptions {
+  /** Ingest base URL, e.g. https://in.lumera.app — native POSTs frames to `${endpoint}/v1/batch`. */
+  endpoint: string;
+  /** Ingest key (pk_…). */
+  siteKey: string;
+  /** Session id shared with the JS structured-event stream so both land on one session. */
+  sessionId: string;
+  /** Session start epoch ms — native derives each frame's relative `t` from this. */
+  startedAtMs: number;
+  /** Capture cadence cap (frames/sec). Change-driven underneath; this only bounds the rate. */
+  fps: number;
+  /** JPEG quality 0..1 on the hot encode path. */
+  jpegQuality: number;
+  /** Cap the longer edge of each captured frame to this many pixels (downscaled on
+   *  device before encode). The dominant storage/bandwidth lever — full native res is
+   *  ~4× larger for no replay benefit. 0 = no cap (full native resolution). */
+  maxCaptureDim: number;
+  /** Privacy-by-default: mask all text/labels/inputs unless explicitly unmasked. */
+  maskAllText: boolean;
+  /** Mask all images/media. */
+  maskAllImages: boolean;
+  /** Capture taps + swipes (native non-blocking gesture observer) as touch events. */
+  captureTouches: boolean;
+  /** How often native flushes its frame buffer to the ingest endpoint. */
+  flushIntervalMs: number;
+}
+
+export interface ConfigureOptions {
+  fps?: number;
+  jpegQuality?: number;
+  maskAllText?: boolean;
+  maskAllImages?: boolean;
+}
+
+export interface NativeDiagnostics {
+  framesCaptured: number;
+  framesSent: number;
+  framesDropped: number;
+  bytesSent: number;
+}
+
+export interface Spec extends TurboModule {
+  /** Begin the native capture loop. All params are primitives — nothing heavy crosses. */
+  start(options: StartOptions): void;
+  /** Stop capture and flush any buffered frames. */
+  stop(): void;
+  /** Live-tune cadence/quality/masking without restarting. */
+  configure(options: ConfigureOptions): void;
+  /** Explicitly mask/unmask a native view by its RN reactTag (powers <LumeraMask>). */
+  setViewMasked(reactTag: number, masked: boolean): void;
+  /** Native-side counters for diagnostics (cheap; async so it never blocks). */
+  getDiagnostics(): Promise<NativeDiagnostics>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('LumeraReplay');

package/src/transport.ts

@@ -0,0 +1,40 @@
+import type { IngestBatch } from '@obsrviq/types';
+
+/**
+ * Ships the structured-event stream (network / error / console / custom) to the same
+ * `POST /v1/batch` endpoint the web tracker uses, with the identical `IngestBatch`
+ * shape. We send uncompressed JSON here — the stream is small (no DOM/replay) and the
+ * ingest endpoint sniffs gzip magic bytes, so plain JSON is accepted. The heavy
+ * screenshot frames are gzipped + uploaded by the native module on its own thread.
+ */
+export class Transport {
+  constructor(
+    private readonly endpoint: string,
+    private readonly siteKey: string,
+  ) {}
+
+  /** The ingest URL — also used by the network instrument to skip self-recording. */
+  get batchUrl(): string {
+    return `${this.endpoint.replace(/\/$/, '')}/v1/batch`;
+  }
+
+  async send(batch: IngestBatch): Promise<boolean> {
+    try {
+      const res = await fetch(this.batchUrl, {
+        method: 'POST',
+        headers: {
+          // MUST be octet-stream (not application/json): the ingest reads the raw
+          // request buffer via a catch-all content-type parser and sniffs gzip itself.
+          // `application/json` would hit Fastify's built-in JSON parser, leaving the
+          // route's Buffer.isBuffer() check false → 400 "empty_body". (Matches the web tracker.)
+          'content-type': 'application/octet-stream',
+          'x-lumera-key': this.siteKey,
+        },
+        body: JSON.stringify(batch),
+      });
+      return res.ok;
+    } catch {
+      return false; // transient — the caller re-queues
+    }
+  }
+}

package/src/util.ts

@@ -0,0 +1,38 @@
+/** RFC4122 v4 UUID — Hermes/JSC-safe (no dependency on crypto.randomUUID). */
+export function uuid(): string {
+  let s = '';
+  for (let i = 0; i < 36; i++) {
+    if (i === 8 || i === 13 || i === 18 || i === 23) s += '-';
+    else if (i === 14) s += '4';
+    else if (i === 19) s += ((Math.random() * 4) | 8).toString(16);
+    else s += ((Math.random() * 16) | 0).toString(16);
+  }
+  return s;
+}
+
+/**
+ * Relative (`t`, ms since session start) + wall (`ts`, epoch ms) clock. RN/Hermes has
+ * no reliable high-res perf clock, so we anchor `t` to Date.now() at start and guard
+ * monotonicity (a backward wall-clock adjustment can never make `t` go backwards) —
+ * good enough for event ordering at our cadence.
+ */
+export class Clock {
+  private readonly startWall: number;
+  private lastT = 0;
+  constructor(startWall: number = Date.now()) {
+    this.startWall = startWall;
+  }
+  /** ms since session start (monotonic non-decreasing). */
+  now(): number {
+    const t = Math.max(this.lastT, Date.now() - this.startWall);
+    this.lastT = t;
+    return t;
+  }
+  /** epoch ms (for display + server bucketing). */
+  wall(): number {
+    return Date.now();
+  }
+  get startedAt(): number {
+    return this.startWall;
+  }
+}