@goliapkg/sentori-react-native 4.0.0 → 5.1.0

package/src/lifecycle.ts

@@ -1,76 +0,0 @@
-// v2.0 W3 — top-level lifecycle: flush / close.
-//
-// Sentry / OTel parity: a single `flush(timeoutMs?)` that drains
-// every in-flight buffer (events / metrics / track), gated by a
-// timeout so a slow network doesn't hang the host's shutdown path.
-//
-// Use before short-lived process exit (CLI / serverless function /
-// fixture cleanup) to ensure pending captures land before the
-// process dies.
-
-import { flush as flushTransport } from './transport';
-import { flushMetrics } from './metrics';
-import { flushTrack } from './track';
-import { reportInternal } from '@goliapkg/sentori-core';
-
-let _closed = false;
-
-/**
- * Force-flush every pending Sentori buffer (events, metrics,
- * track). Returns when the flush settles or the timeout fires —
- * whichever happens first.
- *
- * Never rejects: per the NEVER rule, individual flush failures
- * are silently absorbed (and self-reported via the internal
- * circuit-breaker), and the resolved promise's value is undefined.
- *
- *     await sentori.flush(5_000)   // wait up to 5 s, then move on
- *     process.exit(0)
- */
-export async function flush(timeoutMs: number = 5_000): Promise<void> {
-  if (_closed) return;
-  try {
-    const drainAll = Promise.all([
-      flushTransport().catch((err) => {
-        reportInternal('flush.transport', err);
-      }),
-      flushMetrics().catch((err) => {
-        reportInternal('flush.metrics', err);
-      }),
-      flushTrack().catch((err) => {
-        reportInternal('flush.track', err);
-      }),
-    ]).then(() => undefined);
-    const timer = new Promise<void>((resolve) => setTimeout(resolve, timeoutMs));
-    await Promise.race([drainAll, timer]);
-  } catch (err) {
-    // Belt-and-braces: even though each branch already has its own
-    // catch, the wrapping race shouldn't be able to surface a
-    // failure to the host either. NEVER rule.
-    reportInternal('flush', err);
-  }
-}
-
-/**
- * Flush + shut down. After `close()`, further capture* calls remain
- * silent no-ops via `_closed` gate. Idempotent — re-calling is safe.
- *
- *     await sentori.close()
- *     // SDK is asleep; no more events go out.
- */
-export async function close(timeoutMs?: number): Promise<void> {
-  await flush(timeoutMs);
-  _closed = true;
-}
-
-/** Test hook — reset the shutdown latch so unit tests don't have to
- *  re-init the whole SDK between cases. */
-export function __resetLifecycleForTests(): void {
-  _closed = false;
-}
-
-/** Internal — capture* implementations check this to short-circuit
- *  after `close()`. */
-export function isClosed(): boolean {
-  return _closed;
-}

package/src/measure.ts

@@ -1,28 +0,0 @@
-// v0.9.0 #14 — `sentori.measureFn(name, fn)`. Profile-lite. Wrap an
-// async (or sync) function call in a span so it shows on the issue
-// detail trace waterfall without writing the boilerplate every time.
-// The full Hermes-sampler profiler (#4) is the deep version of this
-// idea; `measureFn` is the cheap version that doesn't need a native
-// module.
-
-import { startSpan } from '@goliapkg/sentori-core';
-
-export async function measureFn<T>(
-  name: string,
-  fn: () => Promise<T> | T,
-  opts?: { tags?: Record<string, string> },
-): Promise<T> {
-  const span = startSpan('sentori.measureFn', {
-    name,
-    tags: opts?.tags ?? {},
-  });
-  try {
-    const result = await fn();
-    span.finish({ status: 'ok' });
-    return result;
-  } catch (e) {
-    if (e instanceof Error) span.setTag('error.message', e.message);
-    span.finish({ status: 'error' });
-    throw e;
-  }
-}

package/src/metrics.ts

@@ -1,94 +0,0 @@
-// v0.8.3 — custom metrics buffer.
-//
-// `recordMetric(name, value, tags?)` pushes a point into a fixed-size
-// ring. A timer flushes the ring every 30 s (or when the buffer is
-// full); captureException also forces a flush so the metrics line up
-// with the error event in the dashboard. Best-effort: a flush failure
-// drops the batch on the floor — metrics aren't critical telemetry.
-//
-// Why not one fetch per point: noisy loops (`recordMetric('frame', 1)`
-// in a render hook) would burn the JS thread + saturate the device's
-// outgoing connection pool. Batching makes the SDK safe to use as a
-// cheap counter primitive.
-
-import type { SpanContextLike } from '@goliapkg/sentori-core';
-
-import { getConfig, isInitialized } from './config';
-import { sendMetricsBatch } from './transport';
-
-type Point = {
-  name: string;
-  tags?: Record<string, string>;
-  ts: string;
-  value: number;
-};
-
-const MAX_BUFFER = 500;
-const FLUSH_INTERVAL_MS = 30_000;
-
-let _buf: Point[] = [];
-let _timer: ReturnType<typeof setInterval> | null = null;
-
-/**
- * Record a numeric metric point. Cheap to call from a render hook —
- * pushes into a 500-slot ring drained every 30 s (or on overflow).
- *
- * v2.0 — accepts an optional `parent: SpanContextLike` so a metric
- * can be correlated to a span. The dashboard span-detail view joins
- * metric points by `tags.span_id` / `tags.trace_id`.
- *
- *     const span = sentori.startSpan({ name: 'db.query users' })
- *     sentori.recordMetric('db.query.duration_ms', 42, undefined, { parent: span })
- *     span.end({ status: 'ok' })
- */
-export function recordMetric(
-  name: string,
-  value: number,
-  tags?: Record<string, string>,
-  opts?: { parent?: SpanContextLike },
-): void {
-  if (!isInitialized()) return;
-  if (typeof name !== 'string' || name.length === 0 || name.length > 200) return;
-  if (typeof value !== 'number' || !Number.isFinite(value)) return;
-  if (tags && Object.keys(tags).length > 20) return;
-  // Merge span-context tags so the dashboard can join metric points
-  // to the span that produced them without a separate schema column.
-  const finalTags: Record<string, string> | undefined = opts?.parent
-    ? { ...(tags ?? {}), span_id: opts.parent.spanId, trace_id: opts.parent.traceId }
-    : tags;
-  _buf.push({ name, tags: finalTags, ts: new Date().toISOString(), value });
-  if (_buf.length >= MAX_BUFFER) {
-    void flushMetrics();
-  }
-}
-
-export async function flushMetrics(): Promise<void> {
-  if (_buf.length === 0) return;
-  const config = getConfig();
-  if (!config) return;
-  const batch = _buf;
-  _buf = [];
-  await sendMetricsBatch(config.ingestUrl, config.token, batch);
-}
-
-/**
- * Start the 30 s flush timer. Called once from `init()`. Idempotent.
- * `clearMetricsTimer` is exposed for tests / teardown.
- */
-export function startMetricsTimer(): void {
-  if (_timer !== null) return;
-  _timer = setInterval(() => {
-    void flushMetrics();
-  }, FLUSH_INTERVAL_MS);
-  // Don't keep the process alive solely for this timer (Node would).
-  // In RN setInterval is a NoopRef so this is harmless there.
-  (_timer as unknown as { unref?: () => void }).unref?.();
-}
-
-export function __resetMetricsForTests(): void {
-  if (_timer !== null) {
-    clearInterval(_timer);
-    _timer = null;
-  }
-  _buf = [];
-}

package/src/pre-crash-sentinel.ts

@@ -1,140 +0,0 @@
-// v0.9.1 +S4 — pre-crash sentinel.
-//
-// Predictive (vs reactive) telemetry. Subscribes to JS-thread frame
-// timing via requestAnimationFrame and, when a rolling 60-frame
-// window has ≥ 50% of frames slower than 32 ms (i.e. < 30 fps for
-// half the window), emits an `event.kind = nearCrash` to the server.
-// Backend stores it in the same events stream so the dashboard shows
-// "X user sessions had near-crash signals 4 minutes before the
-// actual NSException".
-//
-// Memory pressure / OOM / storage low signals will need native
-// system observers and ship in v1.0. v0.9.1 covers the most common
-// runaway-render-loop case purely from JS.
-
-import { startSpan } from '@goliapkg/sentori-core';
-
-import { getBundleInfo } from './bundle-info';
-import { collectDeviceForSentinel, getAppForSentinel } from './sentinel-context';
-import { getConfig, isInitialized } from './config';
-import { enqueue } from './transport';
-import { uuidV7 } from './uuid';
-import type { Event } from './types';
-
-const FRAME_BUDGET_MS = 32; // < 30 fps
-const WINDOW_FRAMES = 60; // ~1 s at 60 fps
-const TRIP_RATIO = 0.5;
-const COOLDOWN_MS = 60_000; // don't spam: one nearCrash event per minute
-
-let _running = false;
-let _lastFrameAt = 0;
-let _slowFrames = 0;
-let _totalFrames = 0;
-let _lastEmitAt = 0;
-let _channels: Set<string> = new Set();
-
-export type PreCrashChannel =
-  | 'frame-budget-overrun'
-  | 'memory-pressure'  // native, v1.0
-  | 'oom-warning'      // native, v1.0
-  | 'storage-low';     // native, v1.0
-
-export type PreCrashSentinelOptions = {
-  enabled: boolean;
-  channels?: PreCrashChannel[];
-  /** Lower → more sensitive. Default 32 ms (< 30 fps). */
-  frameBudgetMs?: number;
-  /** Fraction of frames in the window that must miss budget. Default 0.5. */
-  tripRatio?: number;
-};
-
-export function startPreCrashSentinel(opts: PreCrashSentinelOptions): void {
-  if (!opts.enabled || _running) return;
-  _running = true;
-  _channels = new Set(opts.channels ?? ['frame-budget-overrun']);
-
-  if (_channels.has('frame-budget-overrun')) {
-    startFrameBudgetWatch(opts.frameBudgetMs ?? FRAME_BUDGET_MS, opts.tripRatio ?? TRIP_RATIO);
-  }
-  // Native channels (memory-pressure, oom-warning, storage-low) hook
-  // through a TODO native module in v1.0.
-}
-
-export function stopPreCrashSentinel(): void {
-  _running = false;
-  _slowFrames = 0;
-  _totalFrames = 0;
-  _channels.clear();
-}
-
-function startFrameBudgetWatch(budgetMs: number, tripRatio: number): void {
-  if (typeof requestAnimationFrame !== 'function') return;
-  _lastFrameAt = Date.now();
-  function tick() {
-    if (!_running) return;
-    const now = Date.now();
-    const delta = now - _lastFrameAt;
-    _lastFrameAt = now;
-    if (delta >= budgetMs) _slowFrames++;
-    _totalFrames++;
-    if (_totalFrames >= WINDOW_FRAMES) {
-      const ratio = _slowFrames / _totalFrames;
-      if (ratio >= tripRatio && now - _lastEmitAt > COOLDOWN_MS) {
-        _lastEmitAt = now;
-        emitNearCrash({
-          slowFrames: _slowFrames,
-          totalFrames: _totalFrames,
-          ratio,
-          windowMs: WINDOW_FRAMES * (budgetMs / 2), // approximate
-          channel: 'frame-budget-overrun',
-        });
-      }
-      _slowFrames = 0;
-      _totalFrames = 0;
-    }
-    requestAnimationFrame(tick);
-  }
-  requestAnimationFrame(tick);
-}
-
-function emitNearCrash(data: {
-  slowFrames: number;
-  totalFrames: number;
-  ratio: number;
-  windowMs: number;
-  channel: PreCrashChannel;
-}): void {
-  if (!isInitialized()) return;
-  const config = getConfig();
-  if (!config) return;
-  const span = startSpan('sentori.nearCrash', {
-    name: data.channel,
-    tags: {
-      'nearCrash.channel': data.channel,
-      'nearCrash.ratio': data.ratio.toFixed(3),
-      'nearCrash.slow_frames': String(data.slowFrames),
-      'nearCrash.total_frames': String(data.totalFrames),
-    },
-  });
-  span.finish({ status: 'ok' });
-  const event: Event = {
-    id: uuidV7(),
-    timestamp: new Date().toISOString(),
-    kind: 'nearCrash',
-    platform: 'javascript',
-    release: config.release,
-    environment: config.environment,
-    device: collectDeviceForSentinel(),
-    app: getAppForSentinel(config.release),
-    ...(getBundleInfo() ? { bundle: getBundleInfo() as { id: string } } : {}),
-    error: {
-      type: 'NearCrash',
-      message: `frame budget overrun: ${(data.ratio * 100).toFixed(0)}% of last ${data.totalFrames} frames slow`,
-      stack: [],
-    },
-    tags: {
-      'nearCrash.channel': data.channel,
-    },
-  };
-  enqueue(event);
-}

package/src/report-security.ts

@@ -1,165 +0,0 @@
-// v1.1 chunk S2 — security event reporting.
-//
-// `sentori.reportSecurity(kind, data)` POSTs a single security event
-// to `/v1/security:report`. Helpers wrap common kinds with the right
-// payload shape so dashboards can rely on it without coordinating
-// schemas with every host app.
-//
-// Why a separate API from `captureException` / `track`: security
-// reports have different retention + access patterns (the trust
-// scoring engine in S3 reads them on a hot path) and conflating
-// them with errors would pollute issue grouping. Single endpoint,
-// no batching: pin mismatches and root-detection signals are
-// low-volume by nature (one per app-lifetime in most cases).
-
-import { getConfig, isInitialized } from './config';
-import { peekInstallId } from './install-id';
-import { getCurrentUserId } from './capture';
-
-const SDK_VERSION = '0.0.0';
-
-export type SecurityReportData = Record<string, unknown>;
-
-/**
- * Report an arbitrary security signal. Fire-and-forget; resolves
- * with the server-assigned event id on success or `null` on any
- * failure (network down, server unhappy, SDK not initialised).
- *
- * Use the dedicated helpers (`reportPinMismatch`, future
- * `reportRootDetected`, …) when their shape applies — the dashboard
- * renders kind-specific panels off the well-known kinds.
- */
-export async function reportSecurity(
-  kind: string,
-  data: SecurityReportData = {},
-): Promise<null | string> {
-  if (!isInitialized()) return null;
-  if (typeof kind !== 'string' || kind.length === 0 || kind.length > 100) {
-    return null;
-  }
-  if (Object.keys(data).length > 40) return null;
-
-  const config = getConfig();
-  if (!config) return null;
-  const body = {
-    kind,
-    data,
-    ts: new Date().toISOString(),
-    userId: getCurrentUserId(),
-    installId: peekInstallId() ?? undefined,
-    release: config.release,
-    environment: config.environment,
-  };
-  try {
-    const resp = await fetch(`${config.ingestUrl}/v1/security:report`, {
-      body: JSON.stringify(body),
-      headers: {
-        Authorization: `Bearer ${config.token}`,
-        'Content-Type': 'application/json',
-        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
-      },
-      method: 'POST',
-    });
-    if (!resp.ok) return null;
-    const parsed = (await resp.json().catch(() => null)) as null | { id?: string };
-    return parsed?.id ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * v1.1 chunk S4 — link the current device's user / install to a
- * federated identity (e.g. a Google sub or Apple `sub`). Idempotent;
- * call on every sign-in. Posts to `/v1/security/link`. The dashboard
- * uses this to stitch the same user across projects in the Posture
- * cross-project view.
- *
- * Privacy: only the opaque OAuth `subject` value travels. Never pass
- * the email, display name, avatar, or any other identity attribute.
- */
-export async function linkFederatedIdentity(args: {
-  provider: string;
-  subject: string;
-  userId?: string;
-}): Promise<boolean> {
-  if (!args || typeof args.provider !== 'string' || args.provider.length === 0) return false;
-  if (typeof args.subject !== 'string' || args.subject.length === 0) return false;
-  if (!isInitialized()) return false;
-  const config = getConfig();
-  if (!config) return false;
-  const installId = peekInstallId() ?? undefined;
-  const body = {
-    provider: args.provider,
-    subject: args.subject,
-    userId: args.userId ?? getCurrentUserId(),
-    installId,
-  };
-  try {
-    const resp = await fetch(`${config.ingestUrl}/v1/security/link`, {
-      body: JSON.stringify(body),
-      headers: {
-        Authorization: `Bearer ${config.token}`,
-        'Content-Type': 'application/json',
-        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
-      },
-      method: 'POST',
-    });
-    return resp.ok;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * TLS certificate pin mismatch — caller observed a server cert that
- * didn't match the configured pin set. Posts `kind = 'pin.mismatch'`
- * with the expected + observed pin (or hash) so the dashboard's
- * Pin anomaly panel can cluster reports by server.
- */
-export async function reportPinMismatch(args: {
-  expected: string;
-  observed: string;
-  /** Hostname the SDK was connecting to. Used by the dashboard to
-   *  cluster reports per server. */
-  serverName: string;
-}): Promise<null | string> {
-  if (!args || typeof args.serverName !== 'string' || args.serverName.length === 0) {
-    return null;
-  }
-  // The serverName rides on the top-level envelope (column-typed on
-  // the server) so dashboard queries don't need to crack the data
-  // JSONB. We still echo it inside `data` for self-contained payloads.
-  if (!isInitialized()) return null;
-  const config = getConfig();
-  if (!config) return null;
-  const body = {
-    kind: 'pin.mismatch',
-    serverName: args.serverName,
-    ts: new Date().toISOString(),
-    userId: getCurrentUserId(),
-    installId: peekInstallId() ?? undefined,
-    release: config.release,
-    environment: config.environment,
-    data: {
-      expected: args.expected,
-      observed: args.observed,
-    },
-  };
-  try {
-    const resp = await fetch(`${config.ingestUrl}/v1/security:report`, {
-      body: JSON.stringify(body),
-      headers: {
-        Authorization: `Bearer ${config.token}`,
-        'Content-Type': 'application/json',
-        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
-      },
-      method: 'POST',
-    });
-    if (!resp.ok) return null;
-    const parsed = (await resp.json().catch(() => null)) as null | { id?: string };
-    return parsed?.id ?? null;
-  } catch {
-    return null;
-  }
-}

package/src/runtime-metrics-fps.ts

@@ -1,137 +0,0 @@
-// v2.1 W2 part 3 — FPS auto-instrument.
-//
-// Rolling 5 s window of inter-frame Δt measured via rAF; emit
-// runtime.fps.p50 + runtime.fps.p95 every 5 s.
-//
-// Perf bedrock (.claude/CLAUDE.md):
-//   • per-tick cost must be < 0.5 ms on a Pixel-5-equivalent
-//     bench → stop-ship gate in W2 part 4 CI
-//   • main-thread sustained < 1 %
-//   • no allocation inside the rAF callback hot path
-//
-// Implementation choices:
-//   • single-frame Δt = perf.now() - prev — cheap, no allocation
-//   • rolling window stored in a fixed-size Float32Array (no
-//     splice / shift — circular buffer write index)
-//   • percentile computed by copying-and-sorting only at emit
-//     time (every 5 s, ~300 floats) — no per-tick sort
-//
-// Bail-outs:
-//   • if requestAnimationFrame isn't available (rare RN host),
-//     never start the loop
-//   • if perf.now() is missing (older RN engines), fall back to
-//     Date.now() — coarser but better than crashing
-
-import { emitMetric } from '@goliapkg/sentori-core';
-
-const TICK_FRAMES_BEFORE_EMIT = 300; // ~5 s at 60 fps
-const SAMPLE_CAP = 600; // safety: 10 s at 60 fps caps memory
-
-let _running = false;
-let _samples = new Float32Array(SAMPLE_CAP);
-let _write = 0;
-let _count = 0;
-let _prev = 0;
-
-function now(): number {
-  // Engines without perf.now() (very old RN runtimes / minimal
-  // JSCore builds) fall back to wall-clock. Date.now() has 1 ms
-  // resolution so FPS readings cap at 1000; good enough.
-  const p = (globalThis as { performance?: { now?: () => number } }).performance;
-  return p?.now ? p.now() : Date.now();
-}
-
-function rafTick(t: number): void {
-  if (!_running) return;
-  if (_prev !== 0) {
-    const dt = t - _prev;
-    if (dt > 0 && dt < 1000) {
-      _samples[_write] = dt;
-      _write = (_write + 1) % SAMPLE_CAP;
-      _count += 1;
-      if (_count >= TICK_FRAMES_BEFORE_EMIT) {
-        emitWindow();
-        _count = 0;
-        _write = 0;
-      }
-    }
-  }
-  _prev = t;
-  requestAnimationFrame(rafTick);
-}
-
-function emitWindow(): void {
-  // Copy + sort. ~300 floats, well under 1 ms even on a slow phone.
-  // Allocation lives outside the per-tick hot path — only at emit.
-  const n = _count;
-  if (n === 0) return;
-  const slice = new Float32Array(n);
-  for (let i = 0; i < n; i++) slice[i] = _samples[i]!;
-  slice.sort();
-  const p50dt = percentile(slice, 0.5);
-  const p95dt = percentile(slice, 0.95);
-  // FPS = 1000 ms / per-frame Δt.
-  const fpsP50 = p50dt > 0 ? Math.round(1000 / p50dt) : 0;
-  // p95 of Δt is the *slowest* 95 % — i.e. when frames are bad.
-  // p95 FPS conventionally means "5 % worst frames as fps".
-  const fpsP5Slow = p95dt > 0 ? Math.round(1000 / p95dt) : 0;
-  emitMetric('runtime.fps.p50', fpsP50);
-  emitMetric('runtime.fps.p95', fpsP5Slow);
-}
-
-function percentile(sorted: Float32Array, q: number): number {
-  if (sorted.length === 0) return 0;
-  // Discrete percentile — index = ceil(q * n) - 1, clamped.
-  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1));
-  return sorted[idx]!;
-}
-
-/** Idempotent start. Safe to call multiple times; only the first
- *  call kicks off the rAF loop. */
-export function startFpsInstrument(): void {
-  if (_running) return;
-  if (typeof requestAnimationFrame !== 'function') return;
-  _running = true;
-  _prev = 0;
-  _count = 0;
-  _write = 0;
-  requestAnimationFrame(rafTick);
-}
-
-/** Stop the loop. Used by tests + by hosts that want to opt out
- *  mid-session. */
-export function stopFpsInstrument(): void {
-  _running = false;
-}
-
-/** Test-only state inspection. */
-export function __peekFpsInstrumentState(): {
-  count: number;
-  running: boolean;
-} {
-  return { count: _count, running: _running };
-}
-
-/** Test-only force-emit (skips the every-300-frames gate). */
-export function __forceEmitFpsForTests(): void {
-  emitWindow();
-  _count = 0;
-  _write = 0;
-}
-
-/** Test-only sample injection so we can assert without spinning
- *  rAF in the test runner. */
-export function __pushSampleForTests(dt: number): void {
-  _samples[_write] = dt;
-  _write = (_write + 1) % SAMPLE_CAP;
-  _count += 1;
-}
-
-/** Test-only reset between runs. */
-export function __resetFpsInstrumentForTests(): void {
-  _running = false;
-  _samples = new Float32Array(SAMPLE_CAP);
-  _write = 0;
-  _count = 0;
-  _prev = 0;
-}