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

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 => {