@goliapkg/sentori-react-native 0.1.0

package/src/__tests__/uuid.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'bun:test';
+
+import { uuidV7 } from '../uuid';
+
+describe('uuidV7', () => {
+  it('produces a 36-char hyphenated UUID with version 7', () => {
+    const u = uuidV7();
+    expect(u).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it('encodes the current ms timestamp in the leading 48 bits', () => {
+    const before = Date.now();
+    const u = uuidV7();
+    const after = Date.now();
+    const tsHex = u.replace(/-/g, '').slice(0, 12);
+    const ts = parseInt(tsHex, 16);
+    expect(ts).toBeGreaterThanOrEqual(before);
+    expect(ts).toBeLessThanOrEqual(after);
+  });
+
+  it('produces unique values across rapid calls', () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 1000; i++) seen.add(uuidV7());
+    expect(seen.size).toBe(1000);
+  });
+
+  it('always sets version 7 nibble', () => {
+    for (let i = 0; i < 100; i++) {
+      expect(uuidV7().charAt(14)).toBe('7');
+    }
+  });
+
+  it('always sets variant to 10xx', () => {
+    for (let i = 0; i < 100; i++) {
+      const ch = uuidV7().charAt(19).toLowerCase();
+      expect('89ab'.includes(ch)).toBe(true);
+    }
+  });
+});

package/src/breadcrumbs.ts

@@ -0,0 +1,33 @@
+import type { Breadcrumb, BreadcrumbType } from './types';
+
+const MAX_BREADCRUMBS = 100;
+
+let _buffer: Breadcrumb[] = [];
+
+export type AddBreadcrumbInput = {
+  type: BreadcrumbType;
+  data: Record<string, unknown>;
+  timestamp?: string;
+};
+
+export const addBreadcrumb = (input: AddBreadcrumbInput): void => {
+  const crumb: Breadcrumb = {
+    timestamp: input.timestamp ?? new Date().toISOString(),
+    type: input.type,
+    data: input.data,
+  };
+  _buffer.push(crumb);
+  if (_buffer.length > MAX_BREADCRUMBS) {
+    _buffer.shift();
+  }
+};
+
+export const getBreadcrumbs = (): Breadcrumb[] => [..._buffer];
+
+export const clearBreadcrumbs = (): void => {
+  _buffer = [];
+};
+
+export const __resetForTests = (): void => {
+  _buffer = [];
+};

package/src/capture.ts

@@ -0,0 +1,108 @@
+import { getConfig, isInitialized } from './config';
+import { getBreadcrumbs } from './breadcrumbs';
+import { parseStack } from './stack';
+import { enqueue } from './transport';
+import { uuidV7 } from './uuid';
+import type { App, Device, Event, SentoriError, Tags, User } from './types';
+
+let _user: User | null = null;
+
+/**
+ * Attach a stable user identifier to events captured after this call.
+ *
+ * PII policy (Phase 16 sub-D): the User shape is intentionally limited
+ * to `{ id?, anonymous? }` — no email, name, IP, or other identifying
+ * fields. Use a hashed / pseudonymous id (e.g. uuid v4 stored in
+ * AsyncStorage on first launch). The server schema enforces the same
+ * shape, so any extra fields you tack on at the JS layer would be
+ * rejected with `validationFailed` and never persisted.
+ *
+ * Pass `null` to clear (e.g. on sign-out).
+ */
+export const setUser = (user: User | null): void => {
+  _user = user;
+};
+
+export const getUser = (): User | null => _user;
+
+export type CaptureExtras = {
+  tags?: Tags;
+  user?: User;
+  fingerprint?: string[];
+};
+
+export const captureError = (error: Error, extras?: CaptureExtras): void => {
+  if (!isInitialized()) return;
+  const config = getConfig();
+  if (!config) return;
+
+  const event: Event = {
+    id: uuidV7(),
+    timestamp: new Date().toISOString(),
+    kind: 'error',
+    platform: 'javascript',
+    release: config.release,
+    environment: config.environment,
+    device: collectDevice(),
+    app: collectApp(config.release),
+    user: extras?.user ?? _user,
+    tags: extras?.tags,
+    breadcrumbs: getBreadcrumbs(),
+    error: errorToObject(error),
+    fingerprint: extras?.fingerprint,
+  };
+
+  enqueue(event);
+};
+
+export const captureException = captureError;
+
+const errorToObject = (error: Error): SentoriError => {
+  const causeRaw = (error as { cause?: unknown }).cause;
+  let cause: SentoriError | null = null;
+  if (causeRaw instanceof Error) {
+    cause = errorToObject(causeRaw);
+  }
+
+  return {
+    type: error.name || 'Error',
+    message: error.message,
+    stack: parseStack(error.stack),
+    cause,
+  };
+};
+
+const collectDevice = (): Device => {
+  let os: Device['os'] = 'other';
+  let osVersion = '0';
+  try {
+    const RN = require('react-native') as {
+      Platform: { OS: string; Version: string | number };
+    };
+    const rnOS = RN.Platform.OS;
+    os = rnOS === 'ios' || rnOS === 'android' || rnOS === 'web' ? rnOS : 'other';
+    osVersion = String(RN.Platform.Version);
+  } catch {
+    // not in RN runtime (jest, bun test)
+  }
+  return { os, osVersion };
+};
+
+const collectApp = (release: string): App => {
+  const m = /^(?:[^@]+@)?([^+]+)(?:\+(.+))?$/.exec(release);
+  const version = m?.[1] ?? '0.0.0';
+  const build = m?.[2];
+
+  let rnVersion = 'unknown';
+  try {
+    rnVersion = (require('react-native/package.json') as { version: string }).version;
+  } catch {
+    // not in RN runtime
+  }
+
+  return {
+    version,
+    build,
+    framework: { name: 'react-native', version: rnVersion },
+  };
+};

package/src/config.ts

@@ -0,0 +1,21 @@
+export type Config = {
+  token: string;
+  release: string;
+  environment: string;
+  ingestUrl: string;
+  enabled: boolean;
+};
+
+let _config: Config | null = null;
+
+export const setConfig = (config: Config): void => {
+  _config = config;
+};
+
+export const getConfig = (): Config | null => _config;
+
+export const isInitialized = (): boolean => _config !== null;
+
+export const __resetForTests = (): void => {
+  _config = null;
+};

package/src/error-boundary.tsx

@@ -0,0 +1,38 @@
+import React, { Component, type ErrorInfo, type ReactNode } from 'react';
+
+import { captureError } from './capture';
+
+export type ErrorBoundaryProps = {
+  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+  children: ReactNode;
+};
+
+type State = { error: Error | null };
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+  state: State = { error: null };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, _info: ErrorInfo): void {
+    captureError(error);
+  }
+
+  reset = (): void => {
+    this.setState({ error: null });
+  };
+
+  render(): ReactNode {
+    const { error } = this.state;
+    const { fallback, children } = this.props;
+    if (error) {
+      if (typeof fallback === 'function') {
+        return fallback(error, this.reset);
+      }
+      return fallback ?? null;
+    }
+    return children;
+  }
+}

package/src/handlers/global.ts

@@ -0,0 +1,36 @@
+import { captureError } from '../capture';
+
+type ErrorUtilsHandler = (error: Error, isFatal?: boolean) => void;
+
+type ErrorUtilsLike = {
+  setGlobalHandler: (handler: ErrorUtilsHandler) => void;
+  getGlobalHandler: () => ErrorUtilsHandler;
+};
+
+let _previous: ErrorUtilsHandler | undefined;
+let _installed = false;
+
+export const installGlobalHandler = (): void => {
+  if (_installed) return;
+
+  const utils = (globalThis as { ErrorUtils?: ErrorUtilsLike }).ErrorUtils;
+  if (!utils || typeof utils.setGlobalHandler !== 'function') return;
+
+  _installed = true;
+  _previous = utils.getGlobalHandler();
+
+  utils.setGlobalHandler((error, isFatal) => {
+    try {
+      captureError(error);
+    } catch {
+      // never throw from the global handler
+    }
+    if (_previous) {
+      try {
+        _previous(error, isFatal);
+      } catch {
+        // ignore previous handler error
+      }
+    }
+  });
+};

package/src/handlers/network.ts

@@ -0,0 +1,70 @@
+import { addBreadcrumb } from '../breadcrumbs';
+
+let _installed = false;
+
+const AUTH_PARAMS = ['token', 'key', 'password', 'secret', 'access_token'];
+
+export const installNetworkHandler = (): void => {
+  if (_installed) return;
+  if (typeof globalThis.fetch !== 'function') return;
+  _installed = true;
+
+  const original = globalThis.fetch;
+
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const start = Date.now();
+    const url = extractUrl(input);
+    const method = (init?.method ??
+      (typeof input !== 'string' && 'method' in (input as Request)
+        ? (input as Request).method
+        : 'GET')) as string;
+
+    try {
+      const resp = await original(input, init);
+      addBreadcrumb({
+        type: 'net',
+        data: {
+          method,
+          url: scrubUrl(url),
+          status: resp.status,
+          durationMs: Date.now() - start,
+        },
+      });
+      return resp;
+    } catch (e) {
+      addBreadcrumb({
+        type: 'net',
+        data: {
+          method,
+          url: scrubUrl(url),
+          status: 0,
+          durationMs: Date.now() - start,
+          error: String(e),
+        },
+      });
+      throw e;
+    }
+  }) as typeof fetch;
+};
+
+const extractUrl = (input: RequestInfo | URL): string => {
+  if (typeof input === 'string') return input;
+  if (input instanceof URL) return input.href;
+  return (input as Request).url;
+};
+
+const scrubUrl = (url: string): string => {
+  try {
+    const u = new URL(url);
+    let modified = false;
+    for (const p of AUTH_PARAMS) {
+      if (u.searchParams.has(p)) {
+        u.searchParams.set(p, '[redacted]');
+        modified = true;
+      }
+    }
+    return modified ? u.toString() : url;
+  } catch {
+    return url;
+  }
+};

package/src/handlers/promise.ts

@@ -0,0 +1,38 @@
+import { captureError } from '../capture';
+
+type RejectionTracker = (opts: {
+  allRejections: boolean;
+  onUnhandled: (id: number, rejection: unknown) => void;
+}) => void;
+
+type HermesInternalLike = {
+  enablePromiseRejectionTracker?: RejectionTracker;
+};
+
+let _installed = false;
+
+export const installPromiseHandler = (): void => {
+  if (_installed) return;
+
+  const hermes = (globalThis as { HermesInternal?: HermesInternalLike })
+    .HermesInternal;
+  if (hermes?.enablePromiseRejectionTracker) {
+    _installed = true;
+    hermes.enablePromiseRejectionTracker({
+      allRejections: true,
+      onUnhandled: (_id, rejection) => {
+        try {
+          const err =
+            rejection instanceof Error ? rejection : new Error(String(rejection));
+          captureError(err);
+        } catch {
+          // never throw
+        }
+      },
+    });
+    return;
+  }
+
+  // No-op fallback: on JSC or older Hermes the SDK can't track rejections
+  // without a polyfill. Users targeting these can call `captureError(err)` manually.
+};

package/src/index.ts

@@ -0,0 +1,37 @@
+import { init } from './init';
+import { addBreadcrumb } from './breadcrumbs';
+import { setUser, getUser, captureError, captureException } from './capture';
+import { ErrorBoundary } from './error-boundary';
+
+export const sentori = {
+  init,
+  addBreadcrumb,
+  setUser,
+  getUser,
+  captureError,
+  captureException,
+  ErrorBoundary,
+};
+
+export default sentori;
+
+export { init } from './init';
+export { addBreadcrumb } from './breadcrumbs';
+export { setUser, getUser, captureError, captureException } from './capture';
+export { ErrorBoundary } from './error-boundary';
+export { triggerNativeCrash } from './native';
+
+export type {
+  Event,
+  SentoriError,
+  Frame,
+  Breadcrumb,
+  BreadcrumbType,
+  Device,
+  DeviceOS,
+  App,
+  User,
+  Tags,
+  EventKind,
+  Platform,
+} from './types';

package/src/init.ts

@@ -0,0 +1,80 @@
+import { setConfig } from './config';
+import { installGlobalHandler } from './handlers/global';
+import { installPromiseHandler } from './handlers/promise';
+import { installNetworkHandler } from './handlers/network';
+import { drainNativePending, setNativeConfig } from './native';
+import { drainOfflineQueue, enqueue, startTransport } from './transport';
+import type { Event } from './types';
+
+declare const __DEV__: boolean | undefined;
+
+export type InitOptions = {
+  /** Project token starting with `st_pk_`. Required. */
+  token: string;
+  /** Release identifier, e.g. `myapp@1.2.3+456`. Required. */
+  release: string;
+  /** Environment label. Defaults to `dev` if `__DEV__`, else `prod`. */
+  environment?: string;
+  /** Override ingestion URL (self-hosted). Default: https://ingest.sentori.golia.jp */
+  ingestUrl?: string;
+  /** Toggle individual capture sources. All enabled by default. */
+  capture?: {
+    globalErrors?: boolean;
+    promiseRejections?: boolean;
+    network?: boolean;
+  };
+};
+
+const DEFAULT_INGEST_URL = 'https://ingest.sentori.golia.jp';
+
+export const init = (options: InitOptions): void => {
+  if (!options.token || !options.token.startsWith('st_pk_')) {
+    throw new Error("Sentori: token is required and must start with 'st_pk_'");
+  }
+  if (!options.release) {
+    throw new Error('Sentori: release is required');
+  }
+
+  const env =
+    options.environment ??
+    (typeof __DEV__ !== 'undefined' && __DEV__ ? 'dev' : 'prod');
+
+  setConfig({
+    token: options.token,
+    release: options.release,
+    environment: env,
+    ingestUrl: options.ingestUrl ?? DEFAULT_INGEST_URL,
+    enabled: true,
+  });
+
+  // Tell the native crash handler about the config so the JSON it writes
+  // on the next NSException / Java uncaught carries release + env.
+  setNativeConfig({
+    token: options.token,
+    release: options.release,
+    environment: env,
+  });
+
+  startTransport();
+
+  const capture = options.capture ?? {};
+  if (capture.globalErrors !== false) installGlobalHandler();
+  if (capture.promiseRejections !== false) installPromiseHandler();
+  if (capture.network !== false) installNetworkHandler();
+
+  // Drain events persisted from previous session (best-effort):
+  // - native crashes from <Documents>/sentori/pending/*.json
+  // - JS transport offline queue from AsyncStorage
+  drainNativePending()
+    .then((items) => {
+      for (const json of items) {
+        try {
+          enqueue(JSON.parse(json) as Event);
+        } catch {
+          // skip malformed
+        }
+      }
+    })
+    .catch(() => {});
+  drainOfflineQueue().catch(() => {});
+};

package/src/native.ts

@@ -0,0 +1,71 @@
+/**
+ * Bridge to the native (iOS / Android) Sentori module.
+ * No-op when not running in an Expo runtime that has the module installed —
+ * this keeps the SDK usable in pure-JS environments (jest, bun test, web).
+ */
+
+type SentoriNativeModule = {
+  drainPending: () => Promise<string[]>
+  setConfig: (config: {
+    environment: string
+    release: string
+    token: string
+  }) => void
+  /** Dev-only — example app uses this to verify the crash flow. */
+  triggerTestNativeCrash?: () => void
+}
+
+let _native: SentoriNativeModule | null | undefined
+
+function native(): SentoriNativeModule | null {
+  if (_native !== undefined) return _native
+  try {
+    const core = require('expo-modules-core') as {
+      requireNativeModule: <T>(name: string) => T
+    }
+    _native = core.requireNativeModule<SentoriNativeModule>('Sentori')
+  } catch {
+    _native = null
+  }
+  return _native
+}
+
+export function setNativeConfig(config: {
+  environment: string
+  release: string
+  token: string
+}): void {
+  try {
+    native()?.setConfig(config)
+  } catch {
+    // never throw on init
+  }
+}
+
+export async function drainNativePending(): Promise<string[]> {
+  const n = native()
+  if (!n) return []
+  try {
+    return await n.drainPending()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Dev-only helper. Triggers a real NSException (iOS) or RuntimeException
+ * (Android) after a short delay so the host app crashes for real and the
+ * native crash handler exercises the full write-to-disk path.
+ *
+ * Usage: tap a button in the example app, watch the app close, restart it,
+ * verify the server received the event.
+ *
+ * No-op when the native module isn't installed (jest, bun test, web).
+ */
+export function triggerNativeCrash(): void {
+  try {
+    native()?.triggerTestNativeCrash?.()
+  } catch {
+    // never throw from a debugging helper
+  }
+}

package/src/stack.ts

@@ -0,0 +1,72 @@
+import type { Frame } from './types';
+
+// V8 / Hermes (RN 0.71+):
+//   "    at functionName (file:line:col)"
+//   "    at file:line:col"
+const V8_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?)(?::(\d+))?(?::(\d+))?\)?\s*$/;
+
+// SpiderMonkey / older Hermes:
+//   "functionName@file:line:col"
+const AT_FRAME = /^(.+?)@(.+?)(?::(\d+))?(?::(\d+))?$/;
+
+export const parseStack = (stack: string | undefined): Frame[] => {
+  if (!stack || typeof stack !== 'string') return [];
+  const lines = stack.split('\n');
+  const frames: Frame[] = [];
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Skip the "ErrorType: message" header line.
+    if (!line.startsWith('at ') && !line.includes('@')) continue;
+
+    const frame = parseV8(line) ?? parseAt(line);
+    if (frame) frames.push(frame);
+  }
+
+  return frames;
+};
+
+const parseV8 = (line: string): Frame | null => {
+  if (!line.startsWith('at ')) return null;
+  const m = V8_FRAME.exec(line);
+  if (!m) return null;
+
+  const fn = m[1] ? m[1].trim() : undefined;
+  const file = m[2] ? m[2].trim() : '<anonymous>';
+  const lineNo = m[3] ? parseInt(m[3], 10) : 0;
+  const col = m[4] ? parseInt(m[4], 10) : undefined;
+
+  return {
+    function: fn,
+    file,
+    line: lineNo,
+    column: col,
+    inApp: isInApp(file),
+  };
+};
+
+const parseAt = (line: string): Frame | null => {
+  const m = AT_FRAME.exec(line);
+  if (!m) return null;
+
+  const fn = m[1] ? m[1].trim() : undefined;
+  const file = m[2] ? m[2].trim() : '<anonymous>';
+  const lineNo = m[3] ? parseInt(m[3], 10) : 0;
+  const col = m[4] ? parseInt(m[4], 10) : undefined;
+
+  return {
+    function: fn,
+    file,
+    line: lineNo,
+    column: col,
+    inApp: isInApp(file),
+  };
+};
+
+const isInApp = (file: string): boolean => {
+  if (!file || file === '<anonymous>') return false;
+  if (file.includes('node_modules/')) return false;
+  if (/^https?:\/\//.test(file)) return false;
+  return true;
+};