@goliapkg/sentori-react-native 1.0.0-rc.8 → 1.0.0

package/src/__tests__/install-id.test.ts

@@ -0,0 +1,60 @@
+// v1.1 chunk S1 — install-id module persistence + race-safety.
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from 'bun:test';
+
+import {
+  __resetInstallIdForTests,
+  getInstallId,
+  peekInstallId,
+} from '../install-id';
+
+describe('install-id', () => {
+  beforeEach(() => {
+    __resetInstallIdForTests();
+  });
+
+  afterEach(() => {
+    __resetInstallIdForTests();
+  });
+
+  it('peekInstallId is null before first resolve', () => {
+    expect(peekInstallId()).toBe(null);
+  });
+
+  it('getInstallId generates a stable id and caches it', async () => {
+    const first = await getInstallId();
+    expect(typeof first).toBe('string');
+    expect(first.length).toBeGreaterThan(10);
+    // sync peek after resolve returns the same value
+    expect(peekInstallId()).toBe(first);
+    // second call returns the cached value
+    expect(await getInstallId()).toBe(first);
+  });
+
+  it('concurrent callers share the same resolve promise', async () => {
+    const [a, b, c] = await Promise.all([
+      getInstallId(),
+      getInstallId(),
+      getInstallId(),
+    ]);
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+  });
+
+  it('produces UUIDv7 shape (variant + version nibble)', async () => {
+    const id = await getInstallId();
+    // RFC 4122 dash positions
+    expect(id[8]).toBe('-');
+    expect(id[13]).toBe('-');
+    expect(id[14]).toBe('7'); // version
+    expect(id[18]).toBe('-');
+    // variant nibble is 8|9|a|b (high 2 bits = 10)
+    expect(['8', '9', 'a', 'b']).toContain(id[19]);
+  });
+});

package/src/__tests__/replay-encoding.test.ts

@@ -0,0 +1,237 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import {
+  __feedTickForTests,
+  __resetReplayForTests,
+  computeDelta,
+  drainReplay,
+} from '../replay';
+
+// Unit coverage for the rc.9 v2 replay encoder.
+//
+// The encoder lives in replay.ts; native module is mocked away via
+// __feedTickForTests so we drive the captureTick body with hand-built
+// snapshots and inspect the resulting NDJSON shape.
+//
+// See docs/replay-encoding-v2.md for the wire schema.
+
+afterEach(() => {
+  __resetReplayForTests();
+});
+
+type Node = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  kind?: string;
+  text?: string;
+  color?: string;
+};
+
+function frame(ts: number, nodes: Node[]) {
+  return JSON.stringify({ ts, width: 1080, height: 2340, nodes });
+}
+
+function nodeRect(x: number, y: number, w: number, h: number, color = '#FF0000FF'): Node {
+  return { x, y, w, h, kind: 'rect', color };
+}
+
+function nodeText(x: number, y: number, w: number, h: number, text: string, color = '#FFFFFFFF'): Node {
+  return { x, y, w, h, kind: 'text', text, color };
+}
+
+function readDrainedLines(): unknown[] {
+  const drained = drainReplay();
+  if (drained.length === 0) return [];
+  return drained.split('\n').map((l) => JSON.parse(l) as unknown);
+}
+
+describe('rc.9 encoder — keyframe vs delta', () => {
+  test('first tick after start always emits a keyframe', () => {
+    __feedTickForTests(frame(1_000, [nodeRect(0, 0, 1080, 2340)]));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(1);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    expect((lines[0] as { width: number }).width).toBe(1080);
+    expect((lines[0] as { nodes: Node[] }).nodes.length).toBe(1);
+  });
+
+  test('static UI ticks emit no line (no-op heartbeat dropped)', () => {
+    const nodes = [nodeRect(0, 0, 1080, 2340, '#000000FF')];
+    __feedTickForTests(frame(1_000, nodes));
+    __feedTickForTests(frame(1_250, nodes));
+    __feedTickForTests(frame(1_500, nodes));
+    __feedTickForTests(frame(1_750, nodes));
+    const lines = readDrainedLines();
+    // 1 keyframe + 0 deltas (all subsequent ticks are no-op)
+    expect(lines.length).toBe(1);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+  });
+
+  test('a single node change emits exactly one delta with the changed node', () => {
+    const baseline = [
+      nodeRect(0, 0, 1080, 2340, '#0E0E10FF'),
+      nodeText(60, 192, 960, 112, 'before'),
+    ];
+    const after = [
+      nodeRect(0, 0, 1080, 2340, '#0E0E10FF'),
+      nodeText(60, 192, 960, 112, 'after'),
+    ];
+    __feedTickForTests(frame(1_000, baseline));
+    __feedTickForTests(frame(1_250, after));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    expect((lines[1] as { kind: string }).kind).toBe('delta');
+    const d = lines[1] as { added: Node[]; changed: Node[]; removed: Node[] };
+    expect(d.added.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+    expect(d.changed.length).toBe(1);
+    expect((d.changed[0] as Node).text).toBe('after');
+  });
+
+  test('added + removed nodes both appear in the delta', () => {
+    const baseline = [nodeRect(0, 0, 1080, 100), nodeRect(0, 200, 1080, 100)];
+    const after = [nodeRect(0, 0, 1080, 100), nodeRect(0, 400, 1080, 100)];
+    __feedTickForTests(frame(1_000, baseline));
+    __feedTickForTests(frame(1_250, after));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    const d = lines[1] as { added: Node[]; changed: Node[]; removed: Node[] };
+    expect(d.added.length).toBe(1);
+    expect((d.added[0] as Node).y).toBe(400);
+    expect(d.removed.length).toBe(1);
+    expect((d.removed[0] as Node).y).toBe(200);
+  });
+
+  test('keyframe overdue ⇒ next emit is a keyframe even when delta is small', () => {
+    const baseline = [nodeRect(0, 0, 1080, 2340), nodeText(60, 192, 960, 112, 'a')];
+    // After 4 s (default keyframeMs), the next change triggers a fresh keyframe.
+    __feedTickForTests(frame(1_000, baseline));
+    const slightlyChanged = [
+      nodeRect(0, 0, 1080, 2340),
+      nodeText(60, 192, 960, 112, 'a-changed'),
+    ];
+    __feedTickForTests(frame(1_000 + 4_001, slightlyChanged));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    expect((lines[1] as { kind: string }).kind).toBe('key'); // overdue → key
+  });
+
+  test('big screen transition (>40% nodes change) prefers a keyframe over a huge delta', () => {
+    const baseline = Array.from({ length: 10 }, (_, i) => nodeRect(0, i * 100, 1080, 90));
+    const after = Array.from({ length: 10 }, (_, i) => nodeRect(0, i * 100 + 500, 1080, 90));
+    __feedTickForTests(frame(1_000, baseline));
+    __feedTickForTests(frame(1_250, after));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    // Delta would be 10 added + 10 removed = 20 changes, > 10 * 0.4 threshold,
+    // so encoder should fall back to keyframe instead.
+    expect((lines[1] as { kind: string }).kind).toBe('key');
+  });
+
+  test('reconstructing keyframe + applied deltas recovers identical final state', () => {
+    // Drive 6 ticks: keyframe + 5 small deltas, then assert reconstruction equals the last input state.
+    const finalNodes: Node[] = [];
+    const baseline = [nodeRect(0, 0, 1080, 2340, '#0E0E10FF')];
+    __feedTickForTests(frame(1_000, baseline));
+    let state: Node[] = [...baseline];
+    for (let i = 0; i < 5; i++) {
+      // Add one row per tick.
+      const row = nodeText(60, 200 + i * 100, 960, 80, `row ${i}`);
+      state = [...state, row];
+      __feedTickForTests(frame(1_000 + (i + 1) * 250, state));
+    }
+    finalNodes.push(...state);
+
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(6);
+    // Reconstruct: start from keyframe, apply each delta in order.
+    let reconstructed = new Map<string, Node>();
+    for (const line of lines) {
+      const l = line as { kind: string; nodes?: Node[]; added?: Node[]; changed?: Node[]; removed?: Pick<Node, 'x' | 'y' | 'w' | 'h'>[] };
+      if (l.kind === 'key') {
+        reconstructed = new Map((l.nodes ?? []).map((n) => [`${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`, n]));
+      } else {
+        for (const r of l.removed ?? []) {
+          reconstructed.delete(`${r.x | 0},${r.y | 0},${r.w | 0},${r.h | 0}`);
+        }
+        for (const a of l.added ?? []) {
+          reconstructed.set(`${a.x | 0},${a.y | 0},${a.w | 0},${a.h | 0}`, a);
+        }
+        for (const c of l.changed ?? []) {
+          reconstructed.set(`${c.x | 0},${c.y | 0},${c.w | 0},${c.h | 0}`, c);
+        }
+      }
+    }
+    expect(reconstructed.size).toBe(finalNodes.length);
+    for (const n of finalNodes) {
+      const got = reconstructed.get(`${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`);
+      expect(got).toBeDefined();
+      expect(got!.kind).toBe(n.kind);
+      expect(got!.text).toBe(n.text);
+      expect(got!.color).toBe(n.color);
+    }
+  });
+
+  test('byte budget — 60 s × 4 Hz dense UI stays below the rc.8 baseline', () => {
+    // Simulate 60 s at 4 Hz = 240 ticks. Dense UI: 100 nodes, 2 nodes
+    // change per tick on average. This mirrors the typical
+    // mostly-static-with-small-animations app shape.
+    const baseNodes = Array.from({ length: 100 }, (_, i) => nodeRect(0, i * 24, 1080, 20));
+    let totalBytes = 0;
+    const tickCount = 240;
+    for (let t = 0; t < tickCount; t++) {
+      // Every 4th tick mutates two nodes.
+      const nodes = baseNodes.map((n, i) => {
+        if (t % 4 === 0 && (i === t % 100 || i === (t + 50) % 100)) {
+          return { ...n, color: t & 1 ? '#FF0000FF' : '#00FF00FF' };
+        }
+        return n;
+      });
+      __feedTickForTests(frame(1_000 + t * 250, nodes));
+    }
+    const drained = drainReplay();
+    totalBytes = drained.length;
+
+    // rc.8 baseline for the same window: 60 × 100 nodes × ~50 bytes/node ≈ 300 KB.
+    // rc.9 target: well under 200 KB.
+    expect(totalBytes).toBeLessThan(200_000);
+    // Sanity: not zero, and dominated by keyframes.
+    expect(totalBytes).toBeGreaterThan(10_000);
+  });
+});
+
+describe('computeDelta', () => {
+  function asMap(nodes: Node[]): Map<string, Node> {
+    return new Map(nodes.map((n) => [`${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`, n]));
+  }
+
+  test('empty-vs-empty produces all-empty delta', () => {
+    const d = computeDelta(new Map(), new Map());
+    expect(d.added.length).toBe(0);
+    expect(d.changed.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+  });
+
+  test('identical state produces no delta', () => {
+    const m = asMap([nodeRect(0, 0, 10, 10), nodeRect(0, 10, 10, 10)]);
+    const d = computeDelta(m, m);
+    expect(d.added.length).toBe(0);
+    expect(d.changed.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+  });
+
+  test('integer-rounds fingerprints so sub-pixel jitter does not register', () => {
+    const prev = asMap([{ x: 0.1, y: 0.2, w: 10.3, h: 10.4, kind: 'rect' }]);
+    const curr = asMap([{ x: 0.4, y: 0.3, w: 10.2, h: 10.1, kind: 'rect' }]);
+    // Fingerprint of both is '0,0,10,10' → matched, no diff fields differ.
+    const d = computeDelta(prev, curr);
+    expect(d.added.length).toBe(0);
+    expect(d.changed.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+  });
+});

package/src/__tests__/report-security.test.ts

@@ -0,0 +1,106 @@
+// v1.1 chunk S2 — reportSecurity + reportPinMismatch round-trip.
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  mock,
+} from 'bun:test';
+
+import { __resetForTests as resetConfig, setConfig } from '../config';
+import { __resetInstallIdForTests, __setInstallIdForTests } from '../install-id';
+import { setUser } from '../capture';
+import { reportPinMismatch, reportSecurity } from '../report-security';
+
+const originalFetch = globalThis.fetch;
+
+describe('reportSecurity', () => {
+  beforeEach(() => {
+    resetConfig();
+    __resetInstallIdForTests();
+    setConfig({
+      token: 'st_pk_test',
+      release: 'app@1.0.0+1',
+      environment: 'test',
+      ingestUrl: 'http://localhost:8080',
+      enabled: true,
+    });
+    setUser({ id: 'u_demo' });
+    __setInstallIdForTests('install-abc');
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    setUser(null);
+  });
+
+  it('posts the report envelope and returns the server id', async () => {
+    const calls: { body: string; url: string }[] = [];
+    globalThis.fetch = mock(async (url: unknown, init: unknown) => {
+      calls.push({
+        body: String((init as { body?: unknown })?.body ?? ''),
+        url: String(url),
+      });
+      return new Response(JSON.stringify({ id: 'sec-1' }), { status: 202 });
+    }) as unknown as typeof fetch;
+
+    const id = await reportSecurity('root.detected', { detector: 'rootbeer' });
+    expect(id).toBe('sec-1');
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe('http://localhost:8080/v1/security:report');
+    const parsed = JSON.parse(calls[0].body) as {
+      data: Record<string, unknown>;
+      installId: string;
+      kind: string;
+      release: string;
+      userId: string;
+    };
+    expect(parsed.kind).toBe('root.detected');
+    expect(parsed.data.detector).toBe('rootbeer');
+    expect(parsed.installId).toBe('install-abc');
+    expect(parsed.userId).toBe('u_demo');
+    expect(parsed.release).toBe('app@1.0.0+1');
+  });
+
+  it('reportPinMismatch flattens to pin.mismatch with serverName', async () => {
+    const calls: { body: string }[] = [];
+    globalThis.fetch = mock(async (_url: unknown, init: unknown) => {
+      calls.push({ body: String((init as { body?: unknown })?.body ?? '') });
+      return new Response(JSON.stringify({ id: 'sec-2' }), { status: 202 });
+    }) as unknown as typeof fetch;
+
+    const id = await reportPinMismatch({
+      expected: 'sha256/AAAA',
+      observed: 'sha256/BBBB',
+      serverName: 'api.example.com',
+    });
+    expect(id).toBe('sec-2');
+    const parsed = JSON.parse(calls[0].body) as {
+      data: { expected: string; observed: string };
+      kind: string;
+      serverName: string;
+    };
+    expect(parsed.kind).toBe('pin.mismatch');
+    expect(parsed.serverName).toBe('api.example.com');
+    expect(parsed.data.expected).toBe('sha256/AAAA');
+    expect(parsed.data.observed).toBe('sha256/BBBB');
+  });
+
+  it('returns null on transport failure rather than throwing', async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error('offline');
+    }) as unknown as typeof fetch;
+
+    const id = await reportSecurity('arbitrary.kind');
+    expect(id).toBe(null);
+  });
+
+  it('drops bad inputs silently', async () => {
+    const id1 = await reportSecurity('');
+    const id2 = await reportPinMismatch({ expected: 'a', observed: 'b', serverName: '' });
+    expect(id1).toBe(null);
+    expect(id2).toBe(null);
+  });
+});

package/src/__tests__/track.test.ts

@@ -0,0 +1,91 @@
+// v1.1 chunk B — analytics `track` buffer + flush.
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  mock,
+} from 'bun:test';
+
+import { __resetForTests as resetConfig, setConfig } from '../config';
+import { setUser } from '../capture';
+import {
+  __peekTrackBuffer,
+  __resetTrackForTests,
+  flushTrack,
+  track,
+} from '../track';
+
+const originalFetch = globalThis.fetch;
+
+describe('track buffer', () => {
+  beforeEach(() => {
+    resetConfig();
+    __resetTrackForTests();
+    setConfig({
+      token: 'st_pk_test',
+      release: 'app@1.0.0+1',
+      environment: 'test',
+      ingestUrl: 'http://localhost:8080',
+      enabled: true,
+    });
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    setUser(null);
+  });
+
+  it('buffers calls and tags them with release + environment', () => {
+    track('checkout.started', { cart: 42 });
+    track('$pageview', undefined, 'Cart');
+    const buf = __peekTrackBuffer();
+    expect(buf.length).toBe(2);
+    expect(buf[0].name).toBe('checkout.started');
+    expect(buf[0].release).toBe('app@1.0.0+1');
+    expect(buf[0].environment).toBe('test');
+    expect(buf[0].props).toEqual({ cart: 42 });
+    expect(buf[1].name).toBe('$pageview');
+    expect(buf[1].route).toBe('Cart');
+  });
+
+  it('attaches the current user id when set', () => {
+    setUser({ id: 'u_abc' });
+    track('signed_in');
+    const buf = __peekTrackBuffer();
+    expect(buf[0].userId).toBe('u_abc');
+  });
+
+  it('drops oversized names + over-cap prop bags silently', () => {
+    track('x'.repeat(201));
+    const tooManyProps: Record<string, number> = {};
+    for (let i = 0; i < 41; i += 1) tooManyProps[`k${i}`] = i;
+    track('big-bag', tooManyProps);
+    expect(__peekTrackBuffer().length).toBe(0);
+  });
+
+  it('flushTrack drains the buffer and POSTs the batch envelope', async () => {
+    const calls: { body: string; url: string }[] = [];
+    globalThis.fetch = mock(async (url: unknown, init: unknown) => {
+      calls.push({
+        body: String((init as { body?: unknown })?.body ?? ''),
+        url: String(url),
+      });
+      return new Response('{}', { status: 202 });
+    }) as unknown as typeof fetch;
+
+    track('a');
+    track('b');
+    await flushTrack();
+
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe('http://localhost:8080/v1/track:batch');
+    const parsed = JSON.parse(calls[0].body) as {
+      events: Array<{ name: string }>;
+    };
+    expect(parsed.events.map((e) => e.name)).toEqual(['a', 'b']);
+    expect(__peekTrackBuffer().length).toBe(0);
+  });
+});

package/src/capture.ts

@@ -18,6 +18,7 @@ import { parseStack } from './stack';
 import { getTrailBuffer } from './trail';
 import { enqueue, sendUserReport, uploadAttachment } from './transport';
 import { uuidV7 } from './uuid';
+import { peekInstallId } from './install-id';
 import { getCachedNetworkType } from './netinfo';
 import { getRecentNativeException } from './native';
 import type { App, AttachmentMeta, Device, Event, SentoriError, Tags, User } from './types';
@@ -459,6 +460,13 @@ const collectDevice = (): Device => {
   const device: Device = { os, osVersion };
   if (locale) device.locale = locale;
   if (networkType) device.networkType = networkType;
+  // v1.1 chunk S1 — stable per-install id. Read sync from the
+  // in-memory cache populated by the install-id module's first
+  // resolve (kicked off from init()). `null` before init resolves —
+  // the field is omitted in that case rather than blocking event
+  // assembly, which sits on the JS thread.
+  const installId = peekInstallId();
+  if (installId) device.installId = installId;
   return device;
 };
 

package/src/heartbeat.ts

@@ -0,0 +1,158 @@
+// Analytics v1 — concurrent-user heartbeat.
+//
+// Once per minute, while the app is in the foreground, POST a tiny
+// `{ sessionId, userId?, release, route?, os?, ts }` body to
+// `/v1/heartbeat`. The server keeps a per-project Valkey ZSET keyed
+// by member (user.id when set, sessionId otherwise) and the
+// dashboard's `Live` page reads the set to render concurrent-user
+// count + per-dim breakdowns.
+//
+// Iron-rule budget (CLAUDE.md):
+// - 1 POST / min foreground only — never fires when backgrounded
+// - ~200 B body
+// - fire-and-forget; never blocks the JS thread, no retries
+// - bounce suppression: if AppState flaps active → inactive → active
+//   inside 30 s, we still fire at most one heartbeat per 30 s
+//
+// The heartbeat is independent of the session ping in
+// `session-tracker.ts`. Session pings fire only at session close
+// (transport-batched); the heartbeat exists *during* the session to
+// signal presence.
+
+import { getConfig } from './config';
+import { getUser } from './capture';
+import { getLastRoute } from './navigation';
+import { uuidV7 } from './uuid';
+
+declare const __DEV__: boolean | undefined;
+
+const DEFAULT_INTERVAL_MS = 60_000;
+const MIN_GAP_MS = 30_000;
+
+type AppStateLike = {
+  addEventListener: (
+    event: 'change',
+    handler: (state: string) => void
+  ) => { remove: () => void };
+  currentState?: string;
+};
+
+let _running = false;
+let _timer: ReturnType<typeof setInterval> | null = null;
+let _appStateSub: null | { remove: () => void } = null;
+let _sessionId: null | string = null;
+let _lastBeatTs = 0;
+let _intervalMs = DEFAULT_INTERVAL_MS;
+
+export type HeartbeatOptions = {
+  /** Override the default 60 s interval. Floor 10 s — anything below
+   *  trips the perf rule and the server's rate-limit anyway. */
+  intervalMs?: number;
+};
+
+export function startHeartbeat(opts: HeartbeatOptions = {}): void {
+  if (_running) return;
+  _running = true;
+  _intervalMs = Math.max(10_000, opts.intervalMs ?? DEFAULT_INTERVAL_MS);
+  _sessionId = uuidV7();
+
+  // AppState gate — only beat while app is in the foreground.
+  let AppState: AppStateLike | undefined;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    AppState = (require('react-native') as { AppState?: AppStateLike }).AppState;
+  } catch {
+    // Not in RN runtime (tests). The interval still runs; the gate
+    // is just permissive. Suppression below still applies.
+    AppState = undefined;
+  }
+
+  const isForeground = (): boolean => {
+    if (!AppState) return true;
+    return (AppState.currentState ?? 'active') === 'active';
+  };
+
+  const beat = () => {
+    if (!_running) return;
+    if (!isForeground()) return;
+    const now = Date.now();
+    if (now - _lastBeatTs < MIN_GAP_MS) return;
+    _lastBeatTs = now;
+    void send();
+  };
+
+  // First beat as soon as we start (so the dashboard sees the user
+  // immediately, not 60 s after launch). Subsequent fires on the
+  // interval. AppState transitions can poke an immediate beat too —
+  // an active resume is a meaningful presence event.
+  beat();
+  _timer = setInterval(beat, _intervalMs);
+
+  if (AppState && typeof AppState.addEventListener === 'function') {
+    _appStateSub = AppState.addEventListener('change', (state) => {
+      if (state === 'active') beat();
+    });
+  }
+}
+
+export function stopHeartbeat(): void {
+  _running = false;
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+  if (_appStateSub) {
+    _appStateSub.remove();
+    _appStateSub = null;
+  }
+  _sessionId = null;
+  _lastBeatTs = 0;
+}
+
+async function send(): Promise<void> {
+  const config = getConfig();
+  if (!config) return;
+  const user = getUser();
+  const body: Record<string, unknown> = {
+    sessionId: _sessionId ?? '',
+    release: config.release,
+    ts: Date.now(),
+  };
+  if (user?.id) body.userId = user.id;
+  const route = getLastRoute();
+  if (route) body.route = route;
+  const os = readOsString();
+  if (os) body.os = os;
+
+  try {
+    await fetch(`${config.ingestUrl}/v1/heartbeat`, {
+      body: JSON.stringify(body),
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+      },
+      method: 'POST',
+    });
+  } catch (e) {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn('[sentori] heartbeat failed (best-effort)', e);
+    }
+  }
+}
+
+function readOsString(): null | string {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const RN = require('react-native') as {
+      Platform: { OS: string; Version: string | number };
+    };
+    return `${RN.Platform.OS} ${RN.Platform.Version}`;
+  } catch {
+    return null;
+  }
+}
+
+export function __resetHeartbeatForTests(): void {
+  stopHeartbeat();
+}