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

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();
+}

package/src/index.ts

@@ -25,7 +25,11 @@ import {
 } from './mobile-vitals';
 import { bindState, recordState, unbindState } from './state-snapshots';
 import { startMoment } from '@goliapkg/sentori-core';
+import { getInstallId } from './install-id';
 import { flushMetrics, recordMetric } from './metrics';
+import { linkFederatedIdentity, reportPinMismatch, reportSecurity } from './report-security';
+import { flushTrack, track } from './track';
+import { queryTrustScore } from './trust-score';
 import { RageTapCapture } from './rage-tap';
 import {
   endSession,
@@ -44,6 +48,13 @@ export const sentori = {
   sendUserFeedback,
   recordMetric,
   flushMetrics,
+  track,
+  flushTrack,
+  getInstallId,
+  reportSecurity,
+  reportPinMismatch,
+  queryTrustScore,
+  linkFederatedIdentity,
   measureFn,
   startMoment,
   bindState,
@@ -87,6 +98,19 @@ export {
 } from './feature-flags';
 export { clearMaskQuery, registerMaskQuery } from './mask';
 export { flushMetrics, recordMetric } from './metrics';
+export { flushTrack, track, type TrackEvent, type TrackProps } from './track';
+export { getInstallId, peekInstallId } from './install-id';
+export {
+  linkFederatedIdentity,
+  reportPinMismatch,
+  reportSecurity,
+  type SecurityReportData,
+} from './report-security';
+export {
+  queryTrustScore,
+  type TrustScore,
+  type TrustSignal,
+} from './trust-score';
 export { measureFn } from './measure';
 export {
   getColdStartMs,

package/src/init.ts

@@ -8,9 +8,12 @@ import {
   markLaunchCompleted,
   runLaunchCrashGuard,
 } from './launch-crash-guard';
+import { getInstallId } from './install-id';
 import { startMetricsTimer } from './metrics';
+import { startTrackTimer } from './track';
 import { drainNativePending, markNativeJsBridgeReady, setNativeConfig } from './native';
 import { getColdStartMs } from './mobile-vitals';
+import { startHeartbeat, type HeartbeatOptions } from './heartbeat';
 import { startSpan } from '@goliapkg/sentori-core';
 import { startControlChannel } from './control-channel';
 import { startLongTaskMonitor } from './long-task-monitor';
@@ -92,6 +95,11 @@ export type InitOptions = {
      *  longTaskMonitor (≥200ms outliers) — sample profiler 看 idle
      *  分布、long-task 看 outliers。 */
     sampleProfiler?: boolean | { flushMs?: number; sampleMs?: number };
+    /** Analytics v1 — live-presence heartbeat. Foreground 1/min
+     *  default; opt out with `false`, or pass an options object
+     *  to tune. Powers the Audience > Live dashboard.
+     *  Iron-rule budget: < 1 KB / min, < 1 ms / call. */
+    heartbeat?: boolean | HeartbeatOptions;
     /** v0.9.0 #3 — launch-crash loop guard. When two consecutive
      *  launches don't reach `markLaunchCompleted()` (typical of an
      *  OTA update with a fatal bug), invoke the host callback with
@@ -193,6 +201,13 @@ export const init = (options: InitOptions): void => {
   startNetworkTypeWatch();
   // v0.8.3 — drain custom-metric ring every 30 s.
   startMetricsTimer();
+  // v1.1 chunk B — drain `sentori.track()` ring every 30 s.
+  startTrackTimer();
+  // v1.1 chunk S1 — warm the install-id cache. Fire-and-forget;
+  // any event captured before the first resolve simply omits
+  // `device.installId`. Subsequent captures pick it up via the
+  // sync `peekInstallId()` read in collectDevice().
+  void getInstallId();
   // v0.9.1 +S4 — pre-crash sentinel. Off by default; opt-in via
   // `capture.preCrashSentinel: true`.
   if (options.capture?.preCrashSentinel === true) {
@@ -240,6 +255,14 @@ export const init = (options: InitOptions): void => {
     startSession();
     installLifecycleHandler();
   }
+  // Analytics v1 — live-presence heartbeat. Foreground 1/min by
+  // default; pass `capture.heartbeat = false` to opt out, or
+  // `{ intervalMs: 30_000 }` to override. The default budget is well
+  // under the "几乎不能造成性能抖动" rule (CLAUDE.md).
+  const heartbeatOpt = capture.heartbeat;
+  if (heartbeatOpt !== false) {
+    startHeartbeat(typeof heartbeatOpt === 'object' ? heartbeatOpt : {});
+  }
 
   // Drain events persisted from previous session (best-effort):
   // - native crashes from <Documents>/sentori/pending/*.json

package/src/install-id.ts

@@ -0,0 +1,146 @@
+// v1.1 chunk S1 — stable per-install identifier.
+//
+// `getInstallId()` returns a UUIDv7 generated on first call and
+// persisted to device storage. The id survives app restarts and, on
+// iOS specifically, app reinstalls (because the Keychain backend is
+// preserved across uninstall — that's the whole point).
+//
+// Storage tier order:
+//   1. `react-native-keychain` (optional peer; iOS + Android Keystore)
+//   2. AsyncStorage (host already needs this for launch-crash-guard /
+//      offline queue, so we don't add a hard new peer dep)
+//   3. Process-memory only (no persistence — covers SSR / tests)
+//
+// Opaque to the host. The id is NOT tied to a `setUser` call; the
+// server doesn't auto-correlate to user identity. It exists purely
+// as a stable device key so the security posture engine (S3) can
+// score per-install signals independently of authentication state.
+
+import { uuidV7 } from '@goliapkg/sentori-core';
+
+import { isAnyNativeModuleLinked } from './native-loader';
+
+const KEYCHAIN_SERVICE = 'sentori.install-id';
+const ASYNC_STORAGE_KEY = '@sentori/install-id';
+
+type AsyncStorageLike = {
+  getItem: (key: string) => Promise<null | string>;
+  setItem: (key: string, value: string) => Promise<void>;
+};
+
+type KeychainModule = {
+  getGenericPassword: (options: {
+    service: string;
+  }) => Promise<false | { password: string; username: string }>;
+  setGenericPassword: (
+    username: string,
+    password: string,
+    options: { service: string },
+  ) => Promise<unknown>;
+};
+
+let _cached: null | string = null;
+let _inflight: null | Promise<string> = null;
+
+function loadKeychain(): KeychainModule | null {
+  // react-native-keychain is the recommended secure-storage peer.
+  // Optional: if the host hasn't installed it we fall through to
+  // AsyncStorage. The Keychain backend is what gives the iOS
+  // "survives reinstall" guarantee.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('react-native-keychain') as KeychainModule;
+    if (typeof mod.getGenericPassword !== 'function') return null;
+    return mod;
+  } catch {
+    return null;
+  }
+}
+
+function loadAsyncStorage(): AsyncStorageLike | null {
+  if (!isAnyNativeModuleLinked(['RNCAsyncStorage', 'AsyncStorageModule'])) {
+    return null;
+  }
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('@react-native-async-storage/async-storage') as {
+      default?: AsyncStorageLike;
+    };
+    return mod.default ?? (mod as unknown as AsyncStorageLike);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the device's stable install id, generating one if absent.
+ * Cached in memory after first resolve so subsequent calls are sync-
+ * adjacent (no storage I/O). Idempotent under concurrent calls — a
+ * second caller during the first resolve awaits the same promise.
+ */
+export async function getInstallId(): Promise<string> {
+  if (_cached !== null) return _cached;
+  if (_inflight !== null) return _inflight;
+  _inflight = (async () => {
+    try {
+      const kc = loadKeychain();
+      if (kc) {
+        const existing = await kc
+          .getGenericPassword({ service: KEYCHAIN_SERVICE })
+          .catch(() => false as const);
+        if (existing && existing.password) {
+          _cached = existing.password;
+          return existing.password;
+        }
+        const fresh = uuidV7();
+        await kc
+          .setGenericPassword('sentori', fresh, { service: KEYCHAIN_SERVICE })
+          .catch(() => undefined);
+        _cached = fresh;
+        return fresh;
+      }
+      const storage = loadAsyncStorage();
+      if (storage) {
+        const existing = await storage
+          .getItem(ASYNC_STORAGE_KEY)
+          .catch(() => null);
+        if (existing) {
+          _cached = existing;
+          return existing;
+        }
+        const fresh = uuidV7();
+        await storage.setItem(ASYNC_STORAGE_KEY, fresh).catch(() => undefined);
+        _cached = fresh;
+        return fresh;
+      }
+      // No storage available — generate but don't persist. The id is
+      // still stable for the lifetime of the process which is good
+      // enough for tests / SSR / no-native-modules contexts.
+      const fresh = uuidV7();
+      _cached = fresh;
+      return fresh;
+    } finally {
+      _inflight = null;
+    }
+  })();
+  return _inflight;
+}
+
+/** Sync read of the currently-cached install id. `null` before the
+ *  first `getInstallId()` resolves. Use this in hot paths (event
+ *  payload assembly) that can't await storage; callers should kick
+ *  off `getInstallId()` once at startup to warm the cache. */
+export function peekInstallId(): null | string {
+  return _cached;
+}
+
+export function __resetInstallIdForTests(): void {
+  _cached = null;
+  _inflight = null;
+}
+
+/** For tests + advanced operator flows that need to seed an id from
+ *  an external secure-storage migration. */
+export function __setInstallIdForTests(id: string): void {
+  _cached = id;
+}

package/src/navigation.ts

@@ -28,6 +28,7 @@ import {
   getNativeFrameCounters,
   resetNativeFrameCounters,
 } from './native';
+import { track } from './track';
 import { captureStep } from './trail';
 
 /** Minimal contract: anything with `addListener('state', cb)` and
@@ -38,6 +39,17 @@ export type NavigationRefLike = {
   getCurrentRoute: () => { name: string } | undefined;
 };
 
+/** Process-global last-known route — populated by the navigation
+ *  span path below, read by the analytics heartbeat so its per-tick
+ *  payload includes the screen the user is on right now. Initial null
+ *  when no nav has happened yet (app just launched, dev-launcher,
+ *  splash). */
+let _lastRoute: null | string = null;
+
+export function getLastRoute(): null | string {
+  return _lastRoute;
+}
+
 /**
  * Subscribe to react-navigation state changes and emit a
  * `react.navigation` span per screen (including the initial one),
@@ -85,6 +97,7 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
       openSpanRef.current = span;
       setActiveSpan(span);
       lastRouteRef.current = to;
+      _lastRoute = to;
       lastRouteEnteredAtRef.current = Date.now();
       // v0.8.0-b — dwell on the previous screen surfaces in the
       // session trail. The leaving span's `durationMs` already
@@ -98,6 +111,19 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
           type: 'navigation',
         },
       });
+      // v1.1 chunk B — auto-pageview. Pushed into the track ring
+      // alongside the navigation span so the analytics path sees
+      // every screen entry without app code needing to wire its own
+      // pageview calls. `from`/`dwellMsPrev` ride in props so the
+      // Behavior view (chunk D) can reconstruct the user journey
+      // even when only the track stream is queried.
+      track(
+        '$pageview',
+        prevDwellMs !== null
+          ? { from: from ?? null, dwellMsPrev: prevDwellMs }
+          : { from: from ?? null },
+        to,
+      );
     };
 
     const finishOpenSpanWithDwell = (): null | number => {

package/src/replay.ts

@@ -22,8 +22,13 @@ import { describeWireframeNative } from './native';
 
 declare const __DEV__: boolean | undefined;
 
-/** Default capture interval (4 Hz). Override via `replay.hz`. */
-const TICK_INTERVAL_MS = 250;
+/** Default capture interval (2 Hz). Override via `replay.hz`. rc.10
+ *  rolled this back from rc.9's 4 Hz default: iOS sim measured 1 ms
+ *  per tick on a thin dev panel but extrapolation to a 200-node
+ *  Insight-class UI on Android pushes JS-thread occupancy past 1 %,
+ *  which violates the "几乎不能造成性能抖动" rule. Apps that want
+ *  smoother playback motion can opt into `replay.hz: 4` explicitly. */
+const TICK_INTERVAL_MS = 500;
 
 /** How often to emit a fresh keyframe — caps reconstruction chain
  *  length and lets the player re-sync after a dropped line. */
@@ -79,7 +84,9 @@ let _nativeMod: ReplayNativeModule | null = null;
 
 export type ReplayOptions = {
   mode?: 'off' | 'wireframe';
-  /** Ticks per second. Default 4. */
+  /** Ticks per second. Default 2. Opt into 4 (or 8) for
+   *  motion-heavy apps where playback smoothness matters more than
+   *  the marginal CPU saving. */
   hz?: number;
   /** Keyframe cadence in ms. Default 4000. */
   keyframeMs?: number;
@@ -111,7 +118,7 @@ export function startReplay(opts: ReplayOptions): void {
   _running = true;
   _nativeMod = loadNativeReplay();
   _keyframeIntervalMs = opts.keyframeMs ?? KEYFRAME_INTERVAL_MS;
-  const hz = opts.hz ?? 4;
+  const hz = opts.hz ?? 2;
   const period = Math.max(MIN_TICK_PERIOD_MS, Math.round(1000 / hz));
   _timer = setInterval(() => {
     captureTick();