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

package/src/capture.ts

@@ -1,4 +1,10 @@
-import { sealTrail, shouldSample } from '@goliapkg/sentori-core';
+import {
+  type CaptureMessageOptions,
+  type MessageLevel,
+  safeFn,
+  sealTrail,
+  shouldSample,
+} from '@goliapkg/sentori-core';
 
 import { base64Utf8 } from './base64';
 import {
@@ -18,6 +24,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';
@@ -28,6 +35,41 @@ declare const __DEV__: boolean | undefined;
 
 let _user: User | null = null;
 
+/** v2.0 — global scope tags merged onto every captured event
+ *  (captureException + captureMessage). Set via `setTag` /
+ *  `setTags`; reset by passing `{}`. Per-call tags win on conflict. */
+let _scopeTags: Record<string, string> = {};
+
+/**
+ * v2.0 — set a single scope tag merged onto every subsequent
+ * capture. Per-call `extras.tags` / `opts.tags` win over scope tags.
+ *
+ *     sentori.setTag('rollout', 'dark-mode-v2');
+ *     sentori.captureException(err);  // event.tags carries rollout
+ */
+export const setTag = (key: string, value: string): void => {
+  _scopeTags[key] = String(value);
+};
+
+/**
+ * v2.0 — bulk variant of setTag. Existing tags are merged with
+ * the input record (`Object.assign` style).
+ */
+export const setTags = (record: Record<string, string>): void => {
+  for (const [k, v] of Object.entries(record)) _scopeTags[k] = String(v);
+};
+
+/** Internal — merge global scope tags into a per-call tag record. */
+function mergeScopeTags(perCall: Tags | undefined): Tags | undefined {
+  if (Object.keys(_scopeTags).length === 0) return perCall;
+  return { ..._scopeTags, ...(perCall ?? {}) };
+}
+
+export const __resetScopeForTests = (): void => {
+  _user = null;
+  _scopeTags = {};
+};
+
 // Phase 42 sub-D.08 — per-session screenshot quota. Defaults: 10 in
 // prod, unlimited (-1 sentinel) in dev so test loops + react-error-
 // overlay reruns don't run out partway through the session.
@@ -124,7 +166,7 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
     device: collectDevice(),
     app: collectApp(config.release),
     user: extras?.user ?? _user,
-    tags: extras?.tags,
+    tags: mergeScopeTags(extras?.tags),
     ...(flags ? { flags } : {}),
     ...(bundle ? { bundle } : {}),
     breadcrumbs: crumbs,
@@ -164,7 +206,7 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
   // the server symbolicate at ingest against the uploaded map.
   const pipeline = async (): Promise<void> => {
     if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      await symbolicateErrorViaMetro(event.error).catch(() => {});
+      await symbolicateErrorViaMetro(event.error!).catch(() => {});
     }
     if (wantScreenshot) {
       await captureAndAttachScreenshot(event);
@@ -317,6 +359,65 @@ async function captureAndAttachSessionTrail(event: Event): Promise<void> {
 
 export const captureException = captureError;
 
+const DEFAULT_MESSAGE_LEVEL: MessageLevel = 'info';
+
+/**
+ * Manually report an issue without an Error instance.
+ *
+ * Routes to the dashboard Issues module — distinct from `track`
+ * (analytics) and `recordMetric` (numeric). Use for "operator should
+ * look at this" signals: a fallback that fired, an unexpected state,
+ * a feature flag rollout that crossed a threshold.
+ *
+ *     sentori.captureMessage('Payment provider returned 500, used fallback')
+ *     sentori.captureMessage('Detected impossible state in session reducer', {
+ *       level: 'error',
+ *       tags: { reducer: 'session' },
+ *     })
+ *
+ * Wrapped in `safeFn` per the NEVER rule — any internal failure is
+ * swallowed and (optionally) self-reported; the host app never sees
+ * a thrown error.
+ */
+export const captureMessage = safeFn(
+  'captureMessage',
+  (message: string, opts: CaptureMessageOptions = {}): void => {
+    if (!isInitialized()) return;
+    if (typeof message !== 'string' || message.length === 0) return;
+    const config = getConfig();
+    if (!config) return;
+
+    if (!shouldSample(config.messageSampleRate)) {
+      addBreadcrumb({ type: 'custom', data: { reason: 'sampled-out', kind: 'message' } });
+      return;
+    }
+
+    const flags = getFeatureFlagSnapshot();
+    const bundle = getBundleInfo();
+    const crumbs = opts.breadcrumbs ?? getBreadcrumbs();
+
+    const event: Event = {
+      id: uuidV7(),
+      timestamp: new Date().toISOString(),
+      kind: 'message',
+      level: opts.level ?? DEFAULT_MESSAGE_LEVEL,
+      message,
+      platform: 'javascript',
+      release: config.release,
+      environment: config.environment,
+      device: collectDevice(),
+      app: collectApp(config.release),
+      user: opts.user ?? _user,
+      tags: mergeScopeTags(opts.tags),
+      ...(flags ? { flags } : {}),
+      ...(bundle ? { bundle } : {}),
+      breadcrumbs: crumbs,
+    };
+
+    enqueue(event);
+  },
+);
+
 /** rc.4 — test hook. The real replay attach path is internal so we
  *  don't bloat the public surface, but the encoding bug Insight hit
  *  on 2026-05-18 needs a behaviour-level test that exercises the
@@ -459,6 +560,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/config.ts

@@ -10,6 +10,9 @@ export type Config = {
    *  `null` = keep everything (default). */
   errorSampleRate: null | number;
   traceSampleRate: null | number;
+  /** v2.0 — sampling rate for `kind: 'message'` events emitted via
+   *  `captureMessage`. `null` = keep all (default). */
+  messageSampleRate: null | number;
   /** Phase 46: when true, every `captureException` seals the
    *  session-trail buffer and uploads it as a `sessionTrail`
    *  attachment. Defaults to false. */

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

@@ -3,9 +3,12 @@ import { addBreadcrumb } from './breadcrumbs';
 import {
   captureError,
   captureException,
+  captureMessage,
   captureStep,
   getUser,
   sendUserFeedback,
+  setTag,
+  setTags,
   setUser,
 } from './capture';
 import { ErrorBoundary } from './error-boundary';
@@ -24,8 +27,18 @@ import {
   type TimeToFullDisplayHandle,
 } from './mobile-vitals';
 import { bindState, recordState, unbindState } from './state-snapshots';
-import { startMoment } from '@goliapkg/sentori-core';
+import {
+  startMoment,
+  startSpan,
+  startTrace,
+  withScopedSpan,
+} from '@goliapkg/sentori-core';
+import { getInstallId } from './install-id';
 import { flushMetrics, recordMetric } from './metrics';
+import { close, flush } from './lifecycle';
+import { linkFederatedIdentity, reportPinMismatch, reportSecurity } from './report-security';
+import { flushTrack, track } from './track';
+import { queryTrustScore } from './trust-score';
 import { RageTapCapture } from './rage-tap';
 import {
   endSession,
@@ -38,14 +51,27 @@ export const sentori = {
   addBreadcrumb,
   setUser,
   getUser,
+  setTag,
+  setTags,
   captureError,
   captureException,
+  captureMessage,
   captureStep,
   sendUserFeedback,
   recordMetric,
   flushMetrics,
+  track,
+  flushTrack,
+  getInstallId,
+  reportSecurity,
+  reportPinMismatch,
+  queryTrustScore,
+  linkFederatedIdentity,
   measureFn,
   startMoment,
+  startSpan,
+  startTrace,
+  withScopedSpan,
   bindState,
   recordState,
   unbindState,
@@ -63,6 +89,8 @@ export const sentori = {
   startSession,
   endSession,
   markSessionCrashed,
+  flush,
+  close,
 };
 
 export default sentori;
@@ -72,11 +100,27 @@ export { addBreadcrumb } from './breadcrumbs';
 export {
   captureError,
   captureException,
+  captureMessage,
   captureStep,
   getUser,
   sendUserFeedback,
+  setTag,
+  setTags,
   setUser,
 } from './capture';
+export {
+  startMoment,
+  startSpan,
+  startTrace,
+  withScopedSpan,
+  type SpanContextLike,
+  type StartSpanOptions,
+} from '@goliapkg/sentori-core';
+export { close, flush } from './lifecycle';
+export type {
+  CaptureMessageOptions,
+  MessageLevel,
+} from '@goliapkg/sentori-core';
 export { ErrorBoundary } from './error-boundary';
 export { FeedbackButton, type FeedbackButtonHandle, type FeedbackButtonProps } from './feedback-widget';
 export {
@@ -87,13 +131,26 @@ 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,
   markTimeToFullDisplay,
   type TimeToFullDisplayHandle,
 } from './mobile-vitals';
-export { MomentHandle, type MomentProperties, startMoment } from '@goliapkg/sentori-core';
+export { MomentHandle, type MomentProperties } from '@goliapkg/sentori-core';
 export {
   bindState,
   recordState,

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
@@ -116,6 +124,9 @@ export type InitOptions = {
   sampling?: {
     errors?: null | number;
     traces?: null | number;
+    /** v2.0 — sampling rate for `kind: 'message'` events emitted
+     *  via `sentori.captureMessage()`. `null` / absent → keep all. */
+    messages?: null | number;
   };
 };
 
@@ -155,6 +166,7 @@ export const init = (options: InitOptions): void => {
     screenshotsEnabled: options.capture?.screenshot === true,
     errorSampleRate: options.sampling?.errors ?? null,
     traceSampleRate: options.sampling?.traces ?? null,
+    messageSampleRate: options.sampling?.messages ?? null,
     sessionTrailEnabled: options.capture?.sessionTrail === true,
   });
 
@@ -193,6 +205,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 +259,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;
+}