@goliapkg/sentori-react-native 0.3.1 → 0.5.0

package/src/__tests__/tracing.test.ts

@@ -0,0 +1,108 @@
+import { clearSpans, drainSpans } from '@goliapkg/sentori-core';
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from 'bun:test';
+
+import { installNetworkHandler } from '../handlers/network';
+
+// network.ts installs ONCE per process. To test reliably we:
+//   1. set up a single static recorder on globalThis.fetch
+//   2. install the wrapper exactly once (in beforeAll)
+//   3. between tests, only mutate the recorder's queue — NEVER
+//      re-assign globalThis.fetch, because the wrapper captured the
+//      first reference at install time.
+
+const recorderCalls: Array<{ init?: RequestInit; url: string }> = [];
+let recorderQueue: Array<{ status: number } | Error> = [];
+
+const recorder = (async (input: Request | string | URL, init?: RequestInit) => {
+  const url =
+    typeof input === 'string'
+      ? input
+      : input instanceof URL
+        ? input.toString()
+        : input.url;
+  recorderCalls.push({ init, url });
+  const r = recorderQueue.shift() ?? { status: 200 };
+  if (r instanceof Error) throw r;
+  return new Response('', { status: r.status });
+}) as unknown as typeof fetch;
+
+beforeAll(() => {
+  (globalThis as { fetch: typeof fetch }).fetch = recorder;
+  installNetworkHandler();
+});
+
+beforeEach(() => {
+  clearSpans();
+  recorderCalls.length = 0;
+  recorderQueue = [{ status: 200 }];
+});
+
+afterEach(() => {
+  clearSpans();
+});
+
+describe('RN network handler tracing', () => {
+  test('wrapped fetch emits an http.client span', async () => {
+    const resp = await fetch('https://api.example.com/v1/users/me', {
+      method: 'GET',
+    });
+    expect(resp.status).toBe(200);
+
+    const spans = drainSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0]?.op).toBe('http.client');
+    expect(spans[0]?.name).toBe('GET https://api.example.com/v1/users/me');
+    expect(spans[0]?.tags).toMatchObject({
+      'http.method': 'GET',
+      'http.status': '200',
+      'http.url': 'https://api.example.com/v1/users/me',
+    });
+    expect(spans[0]?.status).toBe('ok');
+  });
+
+  test('injects W3C traceparent header', async () => {
+    await fetch('https://api.example.com/x');
+    expect(recorderCalls).toHaveLength(1);
+    const headers = new Headers(recorderCalls[0]?.init?.headers);
+    const tp = headers.get('traceparent');
+    expect(tp).not.toBeNull();
+    expect(tp).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/);
+  });
+
+  test('5xx → span.status = "error"', async () => {
+    recorderQueue = [{ status: 503 }];
+    await fetch('https://api.example.com/x');
+    expect(drainSpans()[0]?.status).toBe('error');
+  });
+
+  test('throws → status = "error" with error.message tag', async () => {
+    recorderQueue = [new TypeError('NetworkError: offline')];
+    await expect(fetch('https://api.example.com/x')).rejects.toThrow('NetworkError');
+    const sp = drainSpans()[0]!;
+    expect(sp.status).toBe('error');
+    expect(sp.tags['error.message']).toContain('offline');
+  });
+
+  test('AbortError → status = "cancelled"', async () => {
+    recorderQueue = [Object.assign(new Error('aborted'), { name: 'AbortError' })];
+    await expect(fetch('https://api.example.com/x')).rejects.toThrow('aborted');
+    expect(drainSpans()[0]?.status).toBe('cancelled');
+  });
+
+  test('preserves caller-supplied headers alongside traceparent', async () => {
+    await fetch('https://api.example.com/x', {
+      headers: { Authorization: 'Bearer xyz', 'X-Custom': '1' },
+    });
+    const h = new Headers(recorderCalls[0]?.init?.headers);
+    expect(h.get('authorization')).toBe('Bearer xyz');
+    expect(h.get('x-custom')).toBe('1');
+    expect(h.get('traceparent')).toBeTruthy();
+  });
+});

package/src/__tests__/transport.test.ts

@@ -109,4 +109,62 @@ describe('transport', () => {
     expect(capturedHeaders?.Authorization).toBe('Bearer st_pk_test');
     expect(capturedHeaders?.['Sentori-Sdk']).toMatch(/^react-native\//);
   });
+
+  // Phase 33 sub-D: offline / retry behavior.
+
+  it('retries up to MAX_RETRY (3) on a 5xx, then gives up', async () => {
+    let attempts = 0;
+    globalThis.fetch = mock(async () => {
+      attempts++;
+      return new Response('boom', { status: 503 });
+    }) as typeof fetch;
+
+    enqueue(makeEvent('a'));
+    // flush swallows the final throw (and falls through to persist).
+    // We're verifying the retry count, not the throw.
+    await flush();
+    expect(attempts).toBe(3);
+  });
+
+  it('retries on network error (fetch throw), succeeds when recovered', async () => {
+    let attempts = 0;
+    globalThis.fetch = mock(async () => {
+      attempts++;
+      if (attempts < 3) throw new TypeError('NetworkError: offline');
+      return new Response(null, { status: 202 });
+    }) as typeof fetch;
+
+    enqueue(makeEvent('a'));
+    await flush();
+    expect(attempts).toBe(3);
+  });
+
+  it('drops 4xx-other-than-429 without retry (client errors are unrecoverable)', async () => {
+    let attempts = 0;
+    globalThis.fetch = mock(async () => {
+      attempts++;
+      return new Response(null, { status: 400 });
+    }) as typeof fetch;
+
+    enqueue(makeEvent('a'));
+    await flush();
+    // sendOnce treats 4xx-other-than-429 as a no-throw exit, so the
+    // retry loop also exits — one attempt, no double-send.
+    expect(attempts).toBe(1);
+  });
+
+  it('does not duplicate events when flush is called twice in a row', async () => {
+    let attempts = 0;
+    globalThis.fetch = mock(async () => {
+      attempts++;
+      return new Response(null, { status: 202 });
+    }) as typeof fetch;
+
+    enqueue(makeEvent('a'));
+    enqueue(makeEvent('b'));
+    await flush();
+    await flush(); // second flush sees an empty queue and no-ops
+    expect(attempts).toBe(1);
+    expect(__peekQueue()).toHaveLength(0);
+  });
 });

package/src/capture.ts

@@ -1,5 +1,6 @@
 import { getConfig, isInitialized } from './config';
 import { getBreadcrumbs } from './breadcrumbs';
+import { markSessionErrored } from './session-tracker';
 import { parseStack } from './stack';
 import { enqueue } from './transport';
 import { uuidV7 } from './uuid';
@@ -52,6 +53,9 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
     fingerprint: extras?.fingerprint,
   };
 
+  // Phase 26 sub-B: a captured error promotes the current session to
+  // `errored` so the next AppState=background ping reports unhealthy.
+  markSessionErrored();
   enqueue(event);
 };
 

package/src/handlers/lifecycle.ts

@@ -0,0 +1,54 @@
+/**
+ * Phase 26 sub-B: AppState binding.
+ *
+ * Subscribes to AppState transitions:
+ *   - active → start a fresh session (after a previous background end)
+ *   - background / inactive → end the current session
+ *
+ * RN's AppState fires `inactive` on iOS during multitasking peek; we
+ * end on it because that's effectively a background and the user may
+ * not return. If they do, `active` starts a new one — the on-the-wire
+ * session count goes up by one, which matches "the user opened the app
+ * twice". Sentry historically did the opposite (treat inactive as
+ * still alive), but that lets a swiped-away session never end.
+ */
+import { endSession, startSession } from '../session-tracker';
+
+let _installed = false;
+let _subscription: { remove: () => void } | null = null;
+
+type AppStateLike = {
+  addEventListener: (
+    event: 'change',
+    handler: (state: string) => void
+  ) => { remove: () => void };
+};
+
+export const installLifecycleHandler = (): void => {
+  if (_installed) return;
+  _installed = true;
+  let AppState: AppStateLike | undefined;
+  try {
+    // RN ships AppState; in test / non-RN host the require throws and
+    // we silently no-op.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    AppState = (require('react-native') as { AppState?: AppStateLike }).AppState;
+  } catch {
+    return;
+  }
+  if (!AppState || typeof AppState.addEventListener !== 'function') return;
+
+  _subscription = AppState.addEventListener('change', (state) => {
+    if (state === 'active') {
+      startSession();
+    } else if (state === 'background' || state === 'inactive') {
+      endSession();
+    }
+  });
+};
+
+export const __uninstallLifecycleForTests = (): void => {
+  _subscription?.remove();
+  _subscription = null;
+  _installed = false;
+};

package/src/handlers/network.ts

@@ -1,3 +1,5 @@
+import { startSpan } from '@goliapkg/sentori-core';
+
 import { addBreadcrumb } from '../breadcrumbs';
 
 let _installed = false;
@@ -14,29 +16,50 @@ export const installNetworkHandler = (): void => {
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
     const start = Date.now();
     const url = extractUrl(input);
+    const scrubbed = scrubUrl(url);
     const method = (init?.method ??
       (typeof input !== 'string' && 'method' in (input as Request)
         ? (input as Request).method
         : 'GET')) as string;
 
+    // Phase 35 sub-C: also open an http.client span so the request
+    // shows up in the trace waterfall. Breadcrumbs stay — they're
+    // attached to error events at capture time and serve a different
+    // surface (the "last 100 things" timeline on the issue page).
+    const span = startSpan('http.client', {
+      name: `${method.toUpperCase()} ${scrubbed}`,
+      tags: { 'http.method': method.toUpperCase(), 'http.url': scrubbed },
+    });
+
+    // Inject traceparent header on outbound requests.
+    const reqInit: RequestInit = { ...(init ?? {}) };
+    const headers = mergeHeaders(input, init);
+    headers.set('traceparent', toTraceparent(span.traceId, span.spanId));
+    reqInit.headers = headers;
+
     try {
-      const resp = await original(input, init);
+      const resp = await original(input, reqInit);
+      span.setTag('http.status', String(resp.status));
+      span.finish({ status: resp.status >= 400 ? 'error' : 'ok' });
       addBreadcrumb({
         type: 'net',
         data: {
           method,
-          url: scrubUrl(url),
+          url: scrubbed,
           status: resp.status,
           durationMs: Date.now() - start,
         },
       });
       return resp;
     } catch (e) {
+      const isAbort = isAbortError(e);
+      if (e instanceof Error) span.setTag('error.message', e.message);
+      span.finish({ status: isAbort ? 'cancelled' : 'error' });
       addBreadcrumb({
         type: 'net',
         data: {
           method,
-          url: scrubUrl(url),
+          url: scrubbed,
           status: 0,
           durationMs: Date.now() - start,
           error: String(e),
@@ -47,6 +70,28 @@ export const installNetworkHandler = (): void => {
   }) as typeof fetch;
 };
 
+function mergeHeaders(input: RequestInfo | URL, init?: RequestInit): Headers {
+  const out = new Headers();
+  if (typeof input !== 'string' && !(input instanceof URL)) {
+    (input as Request).headers.forEach((v, k) => out.set(k, v));
+  }
+  if (init?.headers) {
+    new Headers(init.headers).forEach((v, k) => out.set(k, v));
+  }
+  return out;
+}
+
+function toTraceparent(traceId: string, spanId: string): string {
+  const trace = traceId.replace(/-/g, '').toLowerCase();
+  const parent = spanId.replace(/-/g, '').toLowerCase().slice(0, 16);
+  return `00-${trace}-${parent}-01`;
+}
+
+function isAbortError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false;
+  return (err as { name?: unknown }).name === 'AbortError';
+}
+
 const extractUrl = (input: RequestInfo | URL): string => {
   if (typeof input === 'string') return input;
   if (input instanceof URL) return input.href;

package/src/index.ts

@@ -2,6 +2,11 @@ import { init } from './init';
 import { addBreadcrumb } from './breadcrumbs';
 import { setUser, getUser, captureError, captureException } from './capture';
 import { ErrorBoundary } from './error-boundary';
+import {
+  endSession,
+  markSessionCrashed,
+  startSession,
+} from './session-tracker';
 
 export const sentori = {
   init,
@@ -11,6 +16,9 @@ export const sentori = {
   captureError,
   captureException,
   ErrorBoundary,
+  startSession,
+  endSession,
+  markSessionCrashed,
 };
 
 export default sentori;
@@ -24,6 +32,12 @@ export {
   stopAnrWatchdog,
   triggerNativeCrash,
 } from './native';
+export {
+  endSession,
+  markSessionCrashed,
+  startSession,
+} from './session-tracker';
+export { type NavigationRefLike, useTraceNavigation } from './navigation';
 
 export type {
   Event,

package/src/native.ts

@@ -12,10 +12,12 @@ type SentoriNativeModule = {
     token: string
   }) => void
   /**
-   * Phase 22 sub-D: opt-in Android ANR watchdog. Posts a tick to the
-   * main looper every `intervalMs`; if not acknowledged within
-   * `timeoutMs`, captures the main-thread stack as an `anr` event.
-   * No-op on iOS today — iOS hang detection lands in sub-E.
+   * Phase 22 sub-D / sub-E: cross-platform main-thread watchdog.
+   * Android: 5 s / 1 s defaults (matches the OS ANR threshold).
+   * iOS: 2 s / 1 s (more aggressive — iOS has no system-level
+   * watchdog signal we can lean on, so we surface stutter Apple's
+   * own runtime never flags).
+   * Reports a `kind = "anr"` event when the main thread is wedged.
    */
   startAnrWatchdog?: (options?: {
     force?: boolean
@@ -83,14 +85,15 @@ export function triggerNativeCrash(): void {
 }
 
 /**
- * Phase 22 sub-D: start the Android ANR watchdog.
+ * Phase 22 sub-D / sub-E: cross-platform main-thread watchdog.
+ * Single JS call covers both Android ANR and iOS hang detection.
  *
- *     startAnrWatchdog()                       // default 5s/1s, prod-only
+ *     startAnrWatchdog()                       // platform defaults, prod-only
  *     startAnrWatchdog({ force: true })        // include debug builds
  *     startAnrWatchdog({ timeoutMs: 3000 })    // tighter threshold
  *
- * Returns silently on iOS / web / jest. iOS hang detection (sub-E)
- * will hook the same JS function once landed.
+ * Defaults: Android 5 s / 1 s tick; iOS 2 s / 1 s tick. Returns
+ * silently on web / jest / unsupported runtimes.
  */
 export function startAnrWatchdog(options?: {
   force?: boolean

package/src/navigation.ts

@@ -0,0 +1,85 @@
+// Phase 35 sub-C: react-navigation auto-instrumentation.
+//
+// Mount `useTraceNavigation(navigationRef)` next to your
+// `<NavigationContainer ref={navigationRef}>` and every route
+// transition becomes a `react.navigation` span. Span names are
+// `<from> → <to>` so the trace list reads as a navigation log.
+//
+// react-navigation is an OPTIONAL peer dependency — apps that
+// don't use it never have to install it. The hook itself doesn't
+// import from @react-navigation/native; consumers pass in the ref
+// they already have, and we read its state via the public
+// `getCurrentRoute()` API. That keeps the dep edge optional.
+
+import { useEffect, useRef } from 'react';
+
+import { startSpan, type SpanHandle } from '@goliapkg/sentori-core';
+
+/** Minimal contract: anything with `addListener('state', cb)` and
+ *  `getCurrentRoute()` works. The real @react-navigation/native
+ *  NavigationContainer ref matches this shape. */
+export type NavigationRefLike = {
+  addListener: (event: 'state', listener: () => void) => () => void;
+  getCurrentRoute: () => { name: string } | undefined;
+};
+
+/**
+ * Subscribe to react-navigation state changes and emit a
+ * `react.navigation` span per transition. First mount records the
+ * initial route as the start anchor but does NOT emit a span (the
+ * convention from `useSentoriRouter` in sentori-react).
+ *
+ *     import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native'
+ *     import { useTraceNavigation } from '@goliapkg/sentori-react-native'
+ *
+ *     function App() {
+ *       const navigationRef = useNavigationContainerRef()
+ *       useTraceNavigation(navigationRef)
+ *       return <NavigationContainer ref={navigationRef}>{...}</NavigationContainer>
+ *     }
+ *
+ * Each span carries `{ from, to }` as tags and uses the destination
+ * route name as the span name.
+ */
+export function useTraceNavigation(navigationRef: NavigationRefLike): void {
+  // Latest route name we've observed. `null` means "no transition
+  // recorded yet" (initial mount).
+  const lastRouteRef = useRef<null | string>(null);
+  // Span that started when this route was entered. Finished when the
+  // NEXT route transition arrives.
+  const openSpanRef = useRef<null | SpanHandle>(null);
+
+  useEffect(() => {
+    if (typeof navigationRef.addListener !== 'function') return;
+    if (typeof navigationRef.getCurrentRoute !== 'function') return;
+
+    // Seed the "last route" reference from the current state so the
+    // first transition emits a span with the right `from`.
+    const initial = navigationRef.getCurrentRoute()?.name ?? null;
+    lastRouteRef.current = initial;
+
+    const unsubscribe = navigationRef.addListener('state', () => {
+      const next = navigationRef.getCurrentRoute()?.name ?? null;
+      const prev = lastRouteRef.current;
+      if (next === null || next === prev) return;
+
+      // Close the prior span (if any) before opening the new one so
+      // the trace looks like a sequence, not nested.
+      openSpanRef.current?.finish({ status: 'ok' });
+
+      const span = startSpan('react.navigation', {
+        name: prev ? `${prev} → ${next}` : next,
+        tags: { 'nav.from': prev ?? '', 'nav.to': next },
+      });
+      openSpanRef.current = span;
+      lastRouteRef.current = next;
+    });
+
+    return () => {
+      unsubscribe();
+      // Close any still-open span on unmount so we don't leak it.
+      openSpanRef.current?.finish({ status: 'ok' });
+      openSpanRef.current = null;
+    };
+  }, [navigationRef]);
+}

package/src/session-tracker.ts

@@ -0,0 +1,53 @@
+/**
+ * Phase 26 sub-B: RN session tracker glue.
+ *
+ * Mirrors the JS SDK's session-tracker but sends through the RN
+ * transport. AppState binding lives in `handlers/lifecycle.ts`; this
+ * file is just the singleton + the start/end/markErrored/markCrashed
+ * surface.
+ */
+import { SessionTracker } from '@goliapkg/sentori-core';
+
+import { getConfig } from './config';
+import { getUser } from './capture';
+import { sendSessionPing } from './transport';
+
+let _tracker: null | SessionTracker = null;
+
+const tracker = (): SessionTracker => {
+  if (_tracker) return _tracker;
+  _tracker = new SessionTracker((ping) => {
+    const cfg = getConfig();
+    if (!cfg) return;
+    void sendSessionPing(cfg.ingestUrl, cfg.token, ping);
+  });
+  return _tracker;
+};
+
+export const startSession = (): void => {
+  const cfg = getConfig();
+  if (!cfg) return;
+  const user = getUser();
+  tracker().start({
+    environment: cfg.environment,
+    release: cfg.release,
+    userId: user?.id ?? null,
+  });
+};
+
+export const endSession = (status?: 'exited'): void => {
+  if (!_tracker) return;
+  _tracker.end(status);
+};
+
+export const markSessionErrored = (): void => {
+  _tracker?.markErrored();
+};
+
+export const markSessionCrashed = (): void => {
+  _tracker?.markCrashed();
+};
+
+export const __resetSessionForTests = (): void => {
+  _tracker = null;
+};

package/src/transport.ts

@@ -162,3 +162,30 @@ export const __resetForTests = (): void => {
 };
 
 export const __peekQueue = (): readonly Event[] => _queue;
+
+/**
+ * Phase 26 sub-B: session ping transport. Best-effort; we don't queue
+ * pings the way we queue events because they fire on background and
+ * AsyncStorage writes during background can be killed by the OS. If
+ * the network's down, the ping is lost — the session counters tolerate
+ * this.
+ */
+export const sendSessionPing = async (
+  ingestUrl: string,
+  token: string,
+  ping: unknown
+): Promise<void> => {
+  try {
+    await fetch(`${ingestUrl}/v1/sessions`, {
+      body: JSON.stringify(ping),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+      },
+      method: 'POST',
+    });
+  } catch {
+    // best-effort
+  }
+};