@goliapkg/sentori-react-native 0.6.0 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goliapkg/sentori-react-native",
-  "version": "0.6.0",
-  "description": "Sentori SDK for React Native — JS-layer error capture, native crash handlers (iOS / Android), batched transport, fetch + react-navigation tracing.",
+  "version": "0.7.0",
+  "description": "Sentori SDK for React Native \u2014 JS-layer error capture, native crash handlers (iOS / Android), batched transport, fetch + react-navigation tracing.",
   "license": "MIT",
   "homepage": "https://sentori.golia.jp",
   "repository": {
@@ -69,6 +69,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@goliapkg/sentori-core": "0.5.0"
+    "@goliapkg/sentori-core": "0.6.0"
   }
 }

package/src/capture.ts

@@ -1,13 +1,18 @@
+import { sealTrail, shouldSample } from '@goliapkg/sentori-core';
+
 import { addBreadcrumb, getBreadcrumbs } from './breadcrumbs';
 import { getConfig, isInitialized } from './config';
 import { symbolicateErrorViaMetro } from './handlers/dev-symbolicate';
 import { captureScreenshot } from './handlers/screenshot';
 import { markSessionErrored } from './session-tracker';
 import { parseStack } from './stack';
+import { getTrailBuffer } from './trail';
 import { enqueue, uploadAttachment } from './transport';
 import { uuidV7 } from './uuid';
 import type { App, AttachmentMeta, Device, Event, SentoriError, Tags, User } from './types';
 
+export { captureStep, __resetTrailForTests } from './trail';
+
 declare const __DEV__: boolean | undefined;
 
 let _user: User | null = null;
@@ -60,6 +65,14 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
   const config = getConfig();
   if (!config) return;
 
+  // Phase 44 sub-B: client-side sampling. Skip the whole pipeline
+  // (no screenshot capture either) when the sample dice come up
+  // wrong. Default rate = null = keep, so existing callers unaffected.
+  if (!shouldSample(config.errorSampleRate)) {
+    addBreadcrumb({ type: 'custom', data: { reason: 'sampled-out', kind: 'error' } });
+    return;
+  }
+
   const event: Event = {
     id: uuidV7(),
     timestamp: new Date().toISOString(),
@@ -97,11 +110,49 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
     if (wantScreenshot) {
       await captureAndAttachScreenshot(event);
     }
+    const trail = getTrailBuffer();
+    if (config.sessionTrailEnabled && trail.size() > 0) {
+      await captureAndAttachSessionTrail(event);
+    }
     enqueue(event);
   };
   void pipeline();
 };
 
+/**
+ * Phase 46 — seal the trail buffer, upload it as a `sessionTrail`
+ * attachment, attach the ref. Best-effort: any failure leaves a
+ * breadcrumb and lets the event ship without the trail.
+ *
+ * The trail is **always cleared** after `captureException`, even if
+ * upload fails — we don't want a stale 30-step buffer leaking into
+ * the next crash's trail.
+ */
+async function captureAndAttachSessionTrail(event: Event): Promise<void> {
+  const trail = getTrailBuffer();
+  const payload = sealTrail(trail);
+  trail.clear();
+  const json = JSON.stringify(payload);
+  // base64 the JSON for the `data:` URI multipart bridge (same
+  // trick the screenshot path uses).
+  const base64 =
+    typeof globalThis.btoa === 'function'
+      ? globalThis.btoa(unescape(encodeURIComponent(json)))
+      : Buffer.from(json, 'utf-8').toString('base64');
+  const attachment = await uploadAttachment(
+    event.id,
+    'sessionTrail',
+    { base64, mediaType: 'application/json' },
+    { source: 'js' },
+  );
+  if (!attachment) {
+    addBreadcrumb({ type: 'custom', data: { reason: 'session-trail-upload-failed' } });
+    return;
+  }
+  if (!event.attachments) event.attachments = [];
+  event.attachments.push(attachment);
+}
+
 export const captureException = captureError;
 
 /** Phase 42 sub-D.08: per-session screenshot quota gate. */

package/src/config.ts

@@ -6,6 +6,14 @@ export type Config = {
   enabled: boolean;
   /** Phase 42 sub-D.07: opt-in screenshot capture on captureException. */
   screenshotsEnabled: boolean;
+  /** Phase 44 sub-B: per-event-class sampling rates 0..1.
+   *  `null` = keep everything (default). */
+  errorSampleRate: null | number;
+  traceSampleRate: null | number;
+  /** Phase 46: when true, every `captureException` seals the
+   *  session-trail buffer and uploads it as a `sessionTrail`
+   *  attachment. Defaults to false. */
+  sessionTrailEnabled: boolean;
 };
 
 let _config: Config | null = null;

package/src/index.ts

@@ -1,6 +1,6 @@
 import { init } from './init';
 import { addBreadcrumb } from './breadcrumbs';
-import { setUser, getUser, captureError, captureException } from './capture';
+import { setUser, getUser, captureError, captureException, captureStep } from './capture';
 import { ErrorBoundary } from './error-boundary';
 import { MaskRegion, setMaskedNode, unsetMaskedNode } from './mask';
 import {
@@ -16,6 +16,7 @@ export const sentori = {
   getUser,
   captureError,
   captureException,
+  captureStep,
   ErrorBoundary,
   MaskRegion,
   setMaskedNode,
@@ -29,7 +30,13 @@ export default sentori;
 
 export { init, init as initSentori } from './init';
 export { addBreadcrumb } from './breadcrumbs';
-export { setUser, getUser, captureError, captureException } from './capture';
+export {
+  captureError,
+  captureException,
+  captureStep,
+  getUser,
+  setUser,
+} from './capture';
 export { ErrorBoundary } from './error-boundary';
 export { MaskRegion, setMaskedNode, unsetMaskedNode } from './mask';
 export {

package/src/init.ts

@@ -5,8 +5,13 @@ import { installPromiseHandler } from './handlers/promise';
 import { installNetworkHandler } from './handlers/network';
 import { drainNativePending, setNativeConfig } from './native';
 import { startSession } from './session-tracker';
-import { drainOfflineQueue, enqueue, startTransport } from './transport';
-import type { Event } from './types';
+import {
+  drainOfflineQueue,
+  enqueue,
+  startTransport,
+  uploadAttachment,
+} from './transport';
+import type { AttachmentKind, AttachmentMeta, AttachmentSource, Event } from './types';
 
 declare const __DEV__: boolean | undefined;
 
@@ -33,6 +38,21 @@ export type InitOptions = {
      *  installed and `<MaskRegion>` placed over any sensitive UI. The
      *  image is webp q=70 480 px max, < 100 KB typical. */
     screenshot?: boolean;
+    /** Phase 46: record the last N steps (route changes, custom
+     *  breadcrumbs) leading up to a crash. On `captureException`
+     *  the buffer is sealed and uploaded as a `sessionTrail`
+     *  attachment. Defaults to false. */
+    sessionTrail?: boolean;
+  };
+  /** Phase 44 sub-B: client-side sampling. Each rate is `[0, 1]`;
+   *  absent / null keeps everything. Defaults to 1.0 for both
+   *  (no drop). Set traces to e.g. 0.1 once the app's at user
+   *  volume to keep ingest budget under control without changing
+   *  the server-side quota. Decisions are made per-event for
+   *  errors and per-trace (all spans together) for traces. */
+  sampling?: {
+    errors?: null | number;
+    traces?: null | number;
   };
 };
 
@@ -57,6 +77,9 @@ export const init = (options: InitOptions): void => {
     ingestUrl: options.ingestUrl ?? DEFAULT_INGEST_URL,
     enabled: true,
     screenshotsEnabled: options.capture?.screenshot === true,
+    errorSampleRate: options.sampling?.errors ?? null,
+    traceSampleRate: options.sampling?.traces ?? null,
+    sessionTrailEnabled: options.capture?.sessionTrail === true,
   });
 
   // Tell the native crash handler about the config so the JSON it writes
@@ -85,10 +108,33 @@ export const init = (options: InitOptions): void => {
   // - native crashes from <Documents>/sentori/pending/*.json
   // - JS transport offline queue from AsyncStorage
   drainNativePending()
-    .then((items) => {
+    .then(async (items) => {
       for (const json of items) {
         try {
-          enqueue(JSON.parse(json) as Event);
+          const event = JSON.parse(json) as Event & {
+            _pendingAttachments?: PendingAttachment[];
+          };
+          // Phase 42 sub-E.05 / F.09: the native crash handler couldn't
+          // upload attachments at crash time (the app was dying); it
+          // base64-encoded them into `_pendingAttachments` instead.
+          // On next launch we upload each before enqueueing the event,
+          // so the dashboard sees the refs in `event.attachments[]`.
+          if (event._pendingAttachments && event._pendingAttachments.length > 0) {
+            for (const p of event._pendingAttachments) {
+              const meta = await uploadAttachment(
+                event.id,
+                p.kind,
+                { base64: p.base64, mediaType: p.mediaType },
+                { source: p.source },
+              );
+              if (meta) {
+                if (!event.attachments) event.attachments = [];
+                event.attachments.push(meta);
+              }
+            }
+            delete event._pendingAttachments;
+          }
+          enqueue(event);
         } catch {
           // skip malformed
         }
@@ -97,3 +143,20 @@ export const init = (options: InitOptions): void => {
     .catch(() => {});
   drainOfflineQueue().catch(() => {});
 };
+
+/**
+ * Phase 42 sub-E.05: shape of each entry in the native crash JSON's
+ * `_pendingAttachments` array. Mirrors what
+ * `SentoriCrashHandler.write` writes on iOS and (sub-F) what
+ * `SentoriCrashWriter` writes on Android.
+ */
+type PendingAttachment = {
+  base64: string;
+  kind: AttachmentKind;
+  mediaType: string;
+  source: AttachmentSource;
+};
+
+// Keep AttachmentMeta in the imports — it's part of the public type
+// surface re-exported from this module's bundle.
+export type { AttachmentMeta };

package/src/navigation.ts

@@ -24,6 +24,8 @@ import { useEffect, useRef } from 'react';
 
 import { setActiveSpan, startSpan, type SpanHandle } from '@goliapkg/sentori-core';
 
+import { captureStep } from './trail';
+
 /** Minimal contract: anything with `addListener('state', cb)` and
  *  `getCurrentRoute()` works. The real @react-navigation/native
  *  NavigationContainer ref matches this shape. */
@@ -72,6 +74,12 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
       openSpanRef.current = span;
       setActiveSpan(span);
       lastRouteRef.current = to;
+      // Phase 46 — record the screen transition into the session trail.
+      // No-op when sessionTrail isn't enabled (the buffer just grows
+      // unbounded until cleared by captureException, but stays cheap).
+      captureStep(`screen:${to}`, {
+        breadcrumb: { type: 'navigation', message: from ? `${from} → ${to}` : to },
+      });
     };
 
     // Open a span for the initial screen so its requests are grouped

package/src/trail.ts

@@ -0,0 +1,32 @@
+// Phase 46 — singleton TrailBuffer for the RN SDK.
+//
+// Kept in its own module so callers (including navigation.ts, which
+// is intentionally lightweight) can record steps without pulling in
+// capture.ts → handlers/screenshot.ts → react-native. The buffer is
+// drained inside capture.ts when an event captures and
+// `sessionTrailEnabled` is on.
+
+import { TrailBuffer, type TrailStep } from '@goliapkg/sentori-core';
+
+const _trail = new TrailBuffer(30);
+
+/**
+ * Phase 46 — record a step into the session-trail buffer. The buffer
+ * is a fixed-size FIFO (default 30 steps); pushing past capacity
+ * drops the oldest entry. Steps are only uploaded if
+ * `init({ capture: { sessionTrail: true } })` is on AND a
+ * `captureException` follows.
+ */
+export const captureStep = (label: string, opts?: Partial<TrailStep>): void => {
+  _trail.push({
+    ts: Date.now(),
+    label,
+    ...(opts ?? {}),
+  });
+};
+
+export const getTrailBuffer = (): TrailBuffer => _trail;
+
+export const __resetTrailForTests = (): void => {
+  _trail.clear();
+};