@lumin-monitor/react-native 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to `@lumin-monitor/react-native` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-05-26
+
+### Fixed
+
+- **`init()` no longer throws under Metro / Expo** ([report]). The 0.1.0–0.2.0
+  releases used a runtime `require("react-native")` inside `detectAppState()`.
+  Metro's static dependency scanner doesn't see requires nested in function
+  bodies, so `react-native` was excluded from the bundle and the call threw
+  `Requiring unknown module "react-native"` at app startup. Replaced with a
+  top-level `import { AppState } from "react-native"`, which Metro picks up
+  and resolves through the consumer's already-installed peer dep. tsup keeps
+  `react-native` externalised so the import survives into the published
+  artifact untouched.
+
+### Changed (BREAKING)
+
+- **AsyncStorage is no longer auto-detected.** The previous behaviour did a
+  runtime `require("@react-native-async-storage/async-storage")`, which has
+  the same Metro problem as the `react-native` require above — and forced
+  every consumer to declare an unused peer dep even when they didn't want
+  persistence. Apps that want persistence now import AsyncStorage themselves
+  and pass it through:
+
+  ```ts
+  import AsyncStorage from "@react-native-async-storage/async-storage";
+  import { init } from "@lumin-monitor/react-native";
+
+  const lumin = init({ apiKey, storage: AsyncStorage });
+  ```
+
+  Omitting `storage` falls back to in-memory ids (the same behaviour 0.2.0
+  exhibited when the optional peer dep wasn't installed). `@react-native-async-storage/async-storage`
+  has been removed from `peerDependencies` and `peerDependenciesMeta`; the
+  SDK itself no longer references the package.
+
+### Migration
+
+- If you were on 0.2.0 and had `@react-native-async-storage/async-storage`
+  installed: import it and pass it as `storage` to `init()`. Two lines of
+  app code.
+- If you didn't have it installed: nothing to change. You were already getting
+  in-memory ids (silently), which is still the default in 0.3.0.
+
+[report]: https://github.com/tamso-labs/lumin/issues  <!-- replace with the actual issue link when filed -->
+
+## [0.2.0] - 2026-05-26
+
+### Added
+
+- `captureError(err, properties?)` — capture an exception as a Lumin event.
+  Accepts a real `Error` (preferred — preserves stack and constructor name as
+  `error_type`), a string, or a plain object with a `message` field. `null` /
+  `undefined` are silently ignored. The same `Error` instance captured twice
+  in one tick is deduped.
+- Automatic capture of unhandled JS errors via `ErrorUtils.setGlobalHandler`.
+  Enabled by default; opt out with `captureUnhandledErrors: false`. The
+  handler **chains to the previous handler**, so RN's red-box, LogBox, and any
+  other error tool already installed still fires — the SDK never swallows the
+  throw.
+- Fatal errors (`isFatal: true`) trigger an immediate `flush()` so the error
+  row has a chance to leave the device before the RN runtime tears down, and
+  are stamped with `properties: { fatal: true }`.
+- `errorUtils` init option — override the auto-detected global ErrorUtils
+  (mainly for tests).
+- New wire `EventType` value `"error"` plus optional `error_message`,
+  `error_stack`, and `error_type` fields on `WireEvent`.
+
+### Notes
+
+- Native iOS / Android crashes are not captured. `ErrorUtils` is JS-only;
+  native crash reporting requires a native module (Crashlytics, Sentry-native,
+  Bugsnag's native bridge) which is out of scope for this SDK.
+- Source maps are not symbolicated server-side. Stacks ship as the RN bundle's
+  minified frames.
+- Requires Lumin API v0.x (this release) or newer — older servers will reject
+  `type: "error"` events with a 400.
+
+## [0.1.0] - 2026-05-26
+
+Initial release. Mirrors `@lumin-monitor/browser` for React Native; same
+`/v1/events` ingest, same `lmn_pub_*` API key kind, so a single Lumin project
+can hold events from web and mobile and tie them to the same user via
+`identify`.
+
+### Added
+
+- `init(options)` returning a `LuminClient` with bound `screen` / `track` /
+  `identify` / `flush` / `close` / `getSessionId` / `getAnonymousId` methods.
+- Synchronous `init()` with lazy AsyncStorage id hydration — buffered events
+  await hydration before the first flush, so apps can call `screen` /
+  `track` immediately after `init`.
+- Persistent `anonymous_id` and `session_id` via
+  `@react-native-async-storage/async-storage` (optional peer dep); graceful
+  in-memory fallback when the peer dep is missing.
+- Idle-based session rotation (`sessionIdleMs`, default 30 min) — matches the
+  GA / Mixpanel convention for mobile sessions.
+- Auto-flush on `AppState` transition to `background` or `inactive`.
+- `screen()` method (RN idiom); emits wire `type: "page"` for cross-platform
+  compatibility with the browser SDK.
+- Optional `@lumin-monitor/react-native/react-navigation` subpath exporting
+  `useLuminScreenviews(client, navigationRef)` for React Navigation v6+ apps.
+- Ships dual ESM + CJS bundle with full `.d.ts` types.
+
+[0.3.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.3.0
+[0.2.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.2.0
+[0.1.0]: https://github.com/tamso-labs/lumin/releases/tag/sdk-react-native-v0.1.0

package/README.md

@@ -13,26 +13,30 @@ the same user.
 ## Install
 
 ```sh
-pnpm add @lumin-monitor/react-native @react-native-async-storage/async-storage
-# or: npm install … / yarn add …
+pnpm add @lumin-monitor/react-native
+# plus, if you want persistent ids across app launches (recommended):
+pnpm add @react-native-async-storage/async-storage
 ```
 
-`@react-native-async-storage/async-storage` is an optional peer dep. The
-SDK uses it to persist `anonymous_id` across app launches and to expire
-`session_id` after 30 minutes of inactivity. If it is not installed, the
-SDK falls back to in-memory ids that reset on every cold start — useful
-for prototypes, but you almost certainly want the peer dep in production.
+`@react-native-async-storage/async-storage` is no longer auto-detected
+(it broke Metro bundling — see [CHANGELOG 0.3.0](./CHANGELOG.md)). Install
+it and pass it to `init({ storage })` to persist `anonymous_id` across app
+launches and let the 30-minute idle session window survive a cold start.
+Omit `storage` (or pass `null`) to use in-memory ids that reset on every
+cold start — fine for prototypes.
 
-React Navigation is also an optional peer dep, only needed if you import
+React Navigation is an optional peer dep, only needed if you import
 `@lumin-monitor/react-native/react-navigation`.
 
 ## Quick start
 
 ```ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
 import { init } from "@lumin-monitor/react-native";
 
 export const lumin = init({
   apiKey: process.env.EXPO_PUBLIC_LUMIN_BROWSER_API_KEY!,
+  storage: AsyncStorage,
 });
 
 // Bound methods, safe to destructure:
@@ -74,6 +78,8 @@ hydration to complete before sending.
 | `fetch`           | global `fetch`                | Override for tests.                                                         |
 | `storage`         | auto-detect AsyncStorage      | Pass a custom `AsyncStorageLike`, or `null` to opt out (in-memory ids).     |
 | `appState`        | auto-detect react-native      | Pass `null` to disable the background-flush listener.                       |
+| `captureUnhandledErrors` | `true`                 | Install an `ErrorUtils.setGlobalHandler` chain. See *Error capture* below.  |
+| `errorUtils`      | auto-detect global ErrorUtils | Override the ErrorUtils-like object the SDK installs into.                  |
 
 ### `screen(name?, properties?)`
 
@@ -115,6 +121,50 @@ identify("user_abc123", { plan: "indie", signedUpAt: "2026-05-01" });
 Re-call on every app launch while the user is signed in. It is cheap
 and ensures a cold start still binds the session.
 
+### `captureError(err, properties?)`
+
+Capture an error. The auto-installed global handler catches uncaught JS
+throws (and rejected promises that bubble up to RN); call this directly
+from `try/catch` blocks where you'd otherwise swallow the failure.
+
+```ts
+try {
+  await applyDiscount(code);
+} catch (err) {
+  captureError(err, { code, step: "checkout" });
+  showToast("Discount didn't apply");
+}
+```
+
+Accepts a real `Error` (preferred — preserves stack and constructor name
+as `error_type`), or any value that will be stringified for the message.
+`null` / `undefined` are silently ignored. The same `Error` object
+captured twice in the same tick is deduped.
+
+### Auto error capture
+
+When `captureUnhandledErrors` is true (the default), the SDK installs a
+handler via `ErrorUtils.setGlobalHandler` that **chains to the previous
+handler**, so RN's red-box, the LogBox, and any other error tool already
+installed still fire. The SDK does not swallow the throw.
+
+Fatal errors (`isFatal: true`) trigger an immediate `flush()` so the
+error row has a chance to leave the device before the RN runtime tears
+down. Best-effort: the OS may suspend the JS thread before the request
+lands, but the standard ~30 s background grace window covers the
+common case.
+
+**What is NOT captured**:
+- **Native iOS / Android crashes.** RN's `ErrorUtils` is JS-only. Native
+  crashes need a native module (Crashlytics, Sentry-native, Bugsnag's
+  native bridge) — out of scope for this SDK.
+- **Source-mapped stacks.** Stacks ship as the minified RN bundle frames
+  ship them. Symbolication against the bundle's source maps is a v2
+  concern.
+
+Opt out with `captureUnhandledErrors: false` if another tool already
+owns the global handler; manual `captureError(err)` still works.
+
 ### `flush(): Promise<void>`
 
 Force a flush of any buffered events. The SDK auto-flushes on AppState

package/dist/index.cjs

@@ -25,6 +25,9 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/client.ts
+var import_react_native = require("react-native");
+
 // src/ids.ts
 function uuidv4() {
   const c = globalThis.crypto;
@@ -41,19 +44,6 @@ function uuidv4() {
 var ANON_KEY = "lumin.anonymous_id";
 var SESSION_KEY = "lumin.session_id";
 var SESSION_LAST_SEEN_KEY = "lumin.session_last_seen";
-function detectAsyncStorage() {
-  try {
-    if (typeof require === "undefined") return null;
-    const mod = require("@react-native-async-storage/async-storage");
-    const candidate = mod?.default ?? mod;
-    if (candidate && typeof candidate.getItem === "function" && typeof candidate.setItem === "function") {
-      return candidate;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
 function memoryStorage() {
   const m = /* @__PURE__ */ new Map();
   return {
@@ -109,6 +99,11 @@ var SERVER_MAX_BATCH = 1e3;
 var DEFAULT_ENDPOINT = "https://api.getlumin.dev";
 var Client = class {
   constructor(opts) {
+    this.prevErrorHandler = void 0;
+    this.errorHandlerInstalled = false;
+    // Dedup the same Error captured twice (e.g. via captureError + the global
+    // handler firing on the same throw). WeakSet so we don't pin GC.
+    this.recentErrors = /* @__PURE__ */ new WeakSet();
     this.userId = null;
     this.cachedIds = null;
     // Pending events queued before ids hydrate. `user_id` is stamped at enqueue
@@ -131,11 +126,14 @@ var Client = class {
       console.warn("[lumin] flush failed", { err, dropped });
     });
     this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
-    const resolvedStorage = opts.storage === null ? memoryStorage() : opts.storage ?? detectAsyncStorage() ?? memoryStorage();
-    this.storage = resolvedStorage;
+    this.storage = opts.storage ?? memoryStorage();
     this.appState = opts.appState === void 0 ? detectAppState() : opts.appState;
+    this.errorUtils = opts.errorUtils === void 0 ? detectErrorUtils() : opts.errorUtils;
     this.idsReady = this.hydrateIds();
     this.installBackgroundFlush();
+    if (opts.captureUnhandledErrors !== false) {
+      this.installErrorHandler();
+    }
   }
   screen(name, properties) {
     if (this.closed) return;
@@ -153,6 +151,22 @@ var Client = class {
     }
     this.enqueue({ type: "track", name, ...properties !== void 0 ? { properties } : {} });
   }
+  captureError(err, properties) {
+    if (this.closed) return;
+    const e = normalizeError(err);
+    if (!e) return;
+    if (typeof err === "object" && err !== null) {
+      if (this.recentErrors.has(err)) return;
+      this.recentErrors.add(err);
+    }
+    this.enqueue({
+      type: "error",
+      ...properties !== void 0 ? { properties } : {},
+      error_message: e.message,
+      ...e.stack ? { error_stack: e.stack } : {},
+      ...e.type ? { error_type: e.type } : {}
+    });
+  }
   identify(userId, traits) {
     if (this.closed) return;
     if (!userId) {
@@ -189,6 +203,7 @@ var Client = class {
     if (this.closed) return;
     this.closed = true;
     this.removeBackgroundFlush();
+    this.restoreErrorHandler();
     await this.flush();
     await Promise.allSettled(this.inflight);
   }
@@ -314,24 +329,88 @@ var Client = class {
       this.appStateSub = null;
     }
   }
+  // --- error handler -----------------------------------------------------
+  /**
+   * Install a global JS error handler via ErrorUtils.setGlobalHandler that
+   * captures + chains to whatever handler was already in place. RN's
+   * red-box and any other observability tool that installed before us
+   * still fires — we do not swallow the throw.
+   */
+  installErrorHandler() {
+    if (!this.errorUtils) return;
+    this.prevErrorHandler = this.errorUtils.getGlobalHandler?.();
+    const handler = (err, isFatal) => {
+      try {
+        this.captureError(err, isFatal ? { fatal: true } : void 0);
+        if (isFatal) void this.flush();
+      } catch {
+      }
+      if (this.prevErrorHandler) {
+        this.prevErrorHandler(err, isFatal);
+      }
+    };
+    this.errorUtils.setGlobalHandler(handler);
+    this.errorHandlerInstalled = true;
+  }
+  restoreErrorHandler() {
+    if (!this.errorHandlerInstalled || !this.errorUtils) return;
+    this.errorUtils.setGlobalHandler(
+      this.prevErrorHandler ?? defaultNoopErrorHandler
+    );
+    this.errorHandlerInstalled = false;
+  }
 };
+function defaultNoopErrorHandler() {
+}
+function detectErrorUtils() {
+  const g = globalThis;
+  const eu = g.ErrorUtils;
+  if (eu && typeof eu.setGlobalHandler === "function") {
+    return eu;
+  }
+  return null;
+}
+function normalizeError(raw) {
+  if (raw == null) return null;
+  if (raw instanceof Error) {
+    return {
+      message: raw.message || raw.name || "Error",
+      ...raw.stack ? { stack: raw.stack } : {},
+      type: raw.name || raw.constructor?.name
+    };
+  }
+  if (typeof raw === "string") {
+    return { message: raw };
+  }
+  if (typeof raw === "object") {
+    const obj = raw;
+    const message = typeof obj.message === "string" ? obj.message : safeStringify(raw);
+    return {
+      message,
+      ...typeof obj.stack === "string" ? { stack: obj.stack } : {},
+      ...typeof obj.name === "string" ? { type: obj.name } : {}
+    };
+  }
+  return { message: String(raw) };
+}
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}
 function clampBatch(n) {
   if (!Number.isFinite(n) || n < 1) return 1;
   if (n > SERVER_MAX_BATCH) return SERVER_MAX_BATCH;
   return Math.floor(n);
 }
 function detectAppState() {
-  try {
-    if (typeof require === "undefined") return null;
-    const rn = require("react-native");
-    const candidate = rn?.AppState;
-    if (candidate && typeof candidate.addEventListener === "function") {
-      return candidate;
-    }
-    return null;
-  } catch {
-    return null;
+  const candidate = import_react_native.AppState;
+  if (candidate && typeof candidate.addEventListener === "function") {
+    return candidate;
   }
+  return null;
 }
 function validateEndpoint(raw) {
   let url;
@@ -369,6 +448,7 @@ function init(opts) {
     screen: c.screen.bind(c),
     track: c.track.bind(c),
     identify: c.identify.bind(c),
+    captureError: c.captureError.bind(c),
     flush: c.flush.bind(c),
     close: c.close.bind(c),
     getSessionId: c.getSessionId.bind(c),

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { L as LuminClient, I as InitOptions } from './types-BeHbtR1J.cjs';
-export { A as AppStateLike, a as AsyncStorageLike, E as EventType, W as WireEvent } from './types-BeHbtR1J.cjs';
+import { L as LuminClient, I as InitOptions } from './types-DMUQWor6.cjs';
+export { A as AppStateLike, a as AsyncStorageLike, E as ErrorUtilsLike, b as EventType, W as WireEvent } from './types-DMUQWor6.cjs';
 
 declare class Client implements LuminClient {
     private readonly endpoint;
@@ -11,6 +11,10 @@ declare class Client implements LuminClient {
     private readonly fetchImpl;
     private readonly storage;
     private readonly appState;
+    private readonly errorUtils;
+    private prevErrorHandler;
+    private errorHandlerInstalled;
+    private readonly recentErrors;
     private userId;
     private idsReady;
     private cachedIds;
@@ -23,6 +27,7 @@ declare class Client implements LuminClient {
     constructor(opts: InitOptions);
     screen(name?: string, properties?: Record<string, unknown>): void;
     track(name: string, properties?: Record<string, unknown>): void;
+    captureError(err: unknown, properties?: Record<string, unknown>): void;
     identify(userId: string, traits?: Record<string, unknown>): void;
     /**
      * Drain the buffer to the server. Returns when the in-flight request
@@ -59,6 +64,14 @@ declare class Client implements LuminClient {
      */
     private installBackgroundFlush;
     private removeBackgroundFlush;
+    /**
+     * Install a global JS error handler via ErrorUtils.setGlobalHandler that
+     * captures + chains to whatever handler was already in place. RN's
+     * red-box and any other observability tool that installed before us
+     * still fires — we do not swallow the throw.
+     */
+    private installErrorHandler;
+    private restoreErrorHandler;
 }
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LuminClient, I as InitOptions } from './types-BeHbtR1J.js';
-export { A as AppStateLike, a as AsyncStorageLike, E as EventType, W as WireEvent } from './types-BeHbtR1J.js';
+import { L as LuminClient, I as InitOptions } from './types-DMUQWor6.js';
+export { A as AppStateLike, a as AsyncStorageLike, E as ErrorUtilsLike, b as EventType, W as WireEvent } from './types-DMUQWor6.js';
 
 declare class Client implements LuminClient {
     private readonly endpoint;
@@ -11,6 +11,10 @@ declare class Client implements LuminClient {
     private readonly fetchImpl;
     private readonly storage;
     private readonly appState;
+    private readonly errorUtils;
+    private prevErrorHandler;
+    private errorHandlerInstalled;
+    private readonly recentErrors;
     private userId;
     private idsReady;
     private cachedIds;
@@ -23,6 +27,7 @@ declare class Client implements LuminClient {
     constructor(opts: InitOptions);
     screen(name?: string, properties?: Record<string, unknown>): void;
     track(name: string, properties?: Record<string, unknown>): void;
+    captureError(err: unknown, properties?: Record<string, unknown>): void;
     identify(userId: string, traits?: Record<string, unknown>): void;
     /**
      * Drain the buffer to the server. Returns when the in-flight request
@@ -59,6 +64,14 @@ declare class Client implements LuminClient {
      */
     private installBackgroundFlush;
     private removeBackgroundFlush;
+    /**
+     * Install a global JS error handler via ErrorUtils.setGlobalHandler that
+     * captures + chains to whatever handler was already in place. RN's
+     * red-box and any other observability tool that installed before us
+     * still fires — we do not swallow the throw.
+     */
+    private installErrorHandler;
+    private restoreErrorHandler;
 }
 
 /**

package/dist/index.js

@@ -1,6 +1,5 @@
-import {
-  __require
-} from "./chunk-3RG5ZIWI.js";
+// src/client.ts
+import { AppState as RNAppState } from "react-native";
 
 // src/ids.ts
 function uuidv4() {
@@ -18,19 +17,6 @@ function uuidv4() {
 var ANON_KEY = "lumin.anonymous_id";
 var SESSION_KEY = "lumin.session_id";
 var SESSION_LAST_SEEN_KEY = "lumin.session_last_seen";
-function detectAsyncStorage() {
-  try {
-    if (typeof __require === "undefined") return null;
-    const mod = __require("@react-native-async-storage/async-storage");
-    const candidate = mod?.default ?? mod;
-    if (candidate && typeof candidate.getItem === "function" && typeof candidate.setItem === "function") {
-      return candidate;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
 function memoryStorage() {
   const m = /* @__PURE__ */ new Map();
   return {
@@ -86,6 +72,11 @@ var SERVER_MAX_BATCH = 1e3;
 var DEFAULT_ENDPOINT = "https://api.getlumin.dev";
 var Client = class {
   constructor(opts) {
+    this.prevErrorHandler = void 0;
+    this.errorHandlerInstalled = false;
+    // Dedup the same Error captured twice (e.g. via captureError + the global
+    // handler firing on the same throw). WeakSet so we don't pin GC.
+    this.recentErrors = /* @__PURE__ */ new WeakSet();
     this.userId = null;
     this.cachedIds = null;
     // Pending events queued before ids hydrate. `user_id` is stamped at enqueue
@@ -108,11 +99,14 @@ var Client = class {
       console.warn("[lumin] flush failed", { err, dropped });
     });
     this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
-    const resolvedStorage = opts.storage === null ? memoryStorage() : opts.storage ?? detectAsyncStorage() ?? memoryStorage();
-    this.storage = resolvedStorage;
+    this.storage = opts.storage ?? memoryStorage();
     this.appState = opts.appState === void 0 ? detectAppState() : opts.appState;
+    this.errorUtils = opts.errorUtils === void 0 ? detectErrorUtils() : opts.errorUtils;
     this.idsReady = this.hydrateIds();
     this.installBackgroundFlush();
+    if (opts.captureUnhandledErrors !== false) {
+      this.installErrorHandler();
+    }
   }
   screen(name, properties) {
     if (this.closed) return;
@@ -130,6 +124,22 @@ var Client = class {
     }
     this.enqueue({ type: "track", name, ...properties !== void 0 ? { properties } : {} });
   }
+  captureError(err, properties) {
+    if (this.closed) return;
+    const e = normalizeError(err);
+    if (!e) return;
+    if (typeof err === "object" && err !== null) {
+      if (this.recentErrors.has(err)) return;
+      this.recentErrors.add(err);
+    }
+    this.enqueue({
+      type: "error",
+      ...properties !== void 0 ? { properties } : {},
+      error_message: e.message,
+      ...e.stack ? { error_stack: e.stack } : {},
+      ...e.type ? { error_type: e.type } : {}
+    });
+  }
   identify(userId, traits) {
     if (this.closed) return;
     if (!userId) {
@@ -166,6 +176,7 @@ var Client = class {
     if (this.closed) return;
     this.closed = true;
     this.removeBackgroundFlush();
+    this.restoreErrorHandler();
     await this.flush();
     await Promise.allSettled(this.inflight);
   }
@@ -291,24 +302,88 @@ var Client = class {
       this.appStateSub = null;
     }
   }
+  // --- error handler -----------------------------------------------------
+  /**
+   * Install a global JS error handler via ErrorUtils.setGlobalHandler that
+   * captures + chains to whatever handler was already in place. RN's
+   * red-box and any other observability tool that installed before us
+   * still fires — we do not swallow the throw.
+   */
+  installErrorHandler() {
+    if (!this.errorUtils) return;
+    this.prevErrorHandler = this.errorUtils.getGlobalHandler?.();
+    const handler = (err, isFatal) => {
+      try {
+        this.captureError(err, isFatal ? { fatal: true } : void 0);
+        if (isFatal) void this.flush();
+      } catch {
+      }
+      if (this.prevErrorHandler) {
+        this.prevErrorHandler(err, isFatal);
+      }
+    };
+    this.errorUtils.setGlobalHandler(handler);
+    this.errorHandlerInstalled = true;
+  }
+  restoreErrorHandler() {
+    if (!this.errorHandlerInstalled || !this.errorUtils) return;
+    this.errorUtils.setGlobalHandler(
+      this.prevErrorHandler ?? defaultNoopErrorHandler
+    );
+    this.errorHandlerInstalled = false;
+  }
 };
+function defaultNoopErrorHandler() {
+}
+function detectErrorUtils() {
+  const g = globalThis;
+  const eu = g.ErrorUtils;
+  if (eu && typeof eu.setGlobalHandler === "function") {
+    return eu;
+  }
+  return null;
+}
+function normalizeError(raw) {
+  if (raw == null) return null;
+  if (raw instanceof Error) {
+    return {
+      message: raw.message || raw.name || "Error",
+      ...raw.stack ? { stack: raw.stack } : {},
+      type: raw.name || raw.constructor?.name
+    };
+  }
+  if (typeof raw === "string") {
+    return { message: raw };
+  }
+  if (typeof raw === "object") {
+    const obj = raw;
+    const message = typeof obj.message === "string" ? obj.message : safeStringify(raw);
+    return {
+      message,
+      ...typeof obj.stack === "string" ? { stack: obj.stack } : {},
+      ...typeof obj.name === "string" ? { type: obj.name } : {}
+    };
+  }
+  return { message: String(raw) };
+}
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}
 function clampBatch(n) {
   if (!Number.isFinite(n) || n < 1) return 1;
   if (n > SERVER_MAX_BATCH) return SERVER_MAX_BATCH;
   return Math.floor(n);
 }
 function detectAppState() {
-  try {
-    if (typeof __require === "undefined") return null;
-    const rn = __require("react-native");
-    const candidate = rn?.AppState;
-    if (candidate && typeof candidate.addEventListener === "function") {
-      return candidate;
-    }
-    return null;
-  } catch {
-    return null;
+  const candidate = RNAppState;
+  if (candidate && typeof candidate.addEventListener === "function") {
+    return candidate;
   }
+  return null;
 }
 function validateEndpoint(raw) {
   let url;
@@ -346,6 +421,7 @@ function init(opts) {
     screen: c.screen.bind(c),
     track: c.track.bind(c),
     identify: c.identify.bind(c),
+    captureError: c.captureError.bind(c),
     flush: c.flush.bind(c),
     close: c.close.bind(c),
     getSessionId: c.getSessionId.bind(c),

package/dist/react-navigation.d.cts

@@ -1,4 +1,4 @@
-import { L as LuminClient } from './types-BeHbtR1J.cjs';
+import { L as LuminClient } from './types-DMUQWor6.cjs';
 
 /**
  * Subset of @react-navigation/native's NavigationContainerRef the hook needs.

package/dist/react-navigation.d.ts

@@ -1,4 +1,4 @@
-import { L as LuminClient } from './types-BeHbtR1J.js';
+import { L as LuminClient } from './types-DMUQWor6.js';
 
 /**
  * Subset of @react-navigation/native's NavigationContainerRef the hook needs.

package/dist/react-navigation.js

@@ -1,5 +1,3 @@
-import "./chunk-3RG5ZIWI.js";
-
 // src/react-navigation.ts
 import { useEffect, useRef } from "react";
 function useLuminScreenviews(client, navigationRef) {

package/dist/{types-BeHbtR1J.d.cts → types-DMUQWor6.d.cts}

@@ -1,4 +1,4 @@
-type EventType = "page" | "track" | "identify";
+type EventType = "page" | "track" | "identify" | "error";
 interface WireEvent {
     ts?: number;
     session_id: string;
@@ -10,6 +10,9 @@ interface WireEvent {
     referrer?: string;
     properties?: Record<string, unknown>;
     trace_id?: string;
+    error_message?: string;
+    error_stack?: string;
+    error_type?: string;
 }
 /**
  * Minimal AsyncStorage shape the SDK actually consumes. Matches both
@@ -58,11 +61,20 @@ interface InitOptions {
      */
     fetch?: typeof fetch;
     /**
-     * Override the AsyncStorage implementation. The SDK auto-detects
-     * `@react-native-async-storage/async-storage` when the peer dep is
-     * installed; pass this only when you bring a different storage backend
-     * (e.g. an MMKV-backed shim) or to disable persistence in tests.
-     * Pass `null` explicitly to opt out of storage entirely (in-memory ids).
+     * Storage backend for the persistent `anonymous_id` and `session_id`.
+     * Pass `AsyncStorage` from `@react-native-async-storage/async-storage`
+     * (recommended) or any object satisfying `AsyncStorageLike`. Omit /
+     * pass `null` for ephemeral in-memory ids that reset on every cold
+     * start.
+     *
+     * The SDK no longer auto-detects AsyncStorage as of 0.3.0 — the
+     * runtime require broke Metro bundling, and forcing every consumer
+     * to install an unused peer dep was the wrong trade. See CHANGELOG.
+     *
+     * ```ts
+     * import AsyncStorage from "@react-native-async-storage/async-storage";
+     * init({ apiKey, storage: AsyncStorage });
+     * ```
      */
     storage?: AsyncStorageLike | null;
     /**
@@ -70,6 +82,31 @@ interface InitOptions {
      * AppState; tests pass a stub.
      */
     appState?: AppStateLike | null;
+    /**
+     * Auto-capture unhandled JS errors via ErrorUtils.setGlobalHandler.
+     * Default true. Set false to disable (e.g. when another tool like Sentry
+     * already owns the global handler). When enabled, the SDK chains to any
+     * previously installed handler so RN's red-box and other reporters
+     * still fire.
+     *
+     * Native crashes (iOS / Android) are NOT captured — that requires native
+     * modules outside this SDK's scope.
+     */
+    captureUnhandledErrors?: boolean;
+    /**
+     * Override the global ErrorUtils-like object the SDK installs into.
+     * The SDK auto-detects React Native's ErrorUtils on globalThis at
+     * runtime; tests pass a stub.
+     */
+    errorUtils?: ErrorUtilsLike | null;
+}
+/**
+ * Minimal shape of React Native's ErrorUtils. The SDK uses these three
+ * methods to chain into any previously installed handler.
+ */
+interface ErrorUtilsLike {
+    setGlobalHandler(handler: (err: unknown, isFatal?: boolean) => void): void;
+    getGlobalHandler?(): ((err: unknown, isFatal?: boolean) => void) | undefined;
 }
 /**
  * Minimal AppState shape the SDK consumes (subset of react-native's AppState).
@@ -85,6 +122,13 @@ interface LuminClient {
     screen(name?: string, properties?: Record<string, unknown>): void;
     track(name: string, properties?: Record<string, unknown>): void;
     identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Capture an error. Accepts a real Error (preferred — preserves stack +
+     * constructor name as error_type), or any value that will be stringified
+     * for error_message. `properties` is forwarded verbatim so callers can
+     * attach context (route, user action, request id).
+     */
+    captureError(err: unknown, properties?: Record<string, unknown>): void;
     flush(): Promise<void>;
     close(): Promise<void>;
     /** Current session id. Resolves once AsyncStorage hydration finishes. */
@@ -93,4 +137,4 @@ interface LuminClient {
     getAnonymousId(): Promise<string>;
 }
 
-export type { AppStateLike as A, EventType as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a };
+export type { AppStateLike as A, ErrorUtilsLike as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a, EventType as b };

package/dist/{types-BeHbtR1J.d.ts → types-DMUQWor6.d.ts}

@@ -1,4 +1,4 @@
-type EventType = "page" | "track" | "identify";
+type EventType = "page" | "track" | "identify" | "error";
 interface WireEvent {
     ts?: number;
     session_id: string;
@@ -10,6 +10,9 @@ interface WireEvent {
     referrer?: string;
     properties?: Record<string, unknown>;
     trace_id?: string;
+    error_message?: string;
+    error_stack?: string;
+    error_type?: string;
 }
 /**
  * Minimal AsyncStorage shape the SDK actually consumes. Matches both
@@ -58,11 +61,20 @@ interface InitOptions {
      */
     fetch?: typeof fetch;
     /**
-     * Override the AsyncStorage implementation. The SDK auto-detects
-     * `@react-native-async-storage/async-storage` when the peer dep is
-     * installed; pass this only when you bring a different storage backend
-     * (e.g. an MMKV-backed shim) or to disable persistence in tests.
-     * Pass `null` explicitly to opt out of storage entirely (in-memory ids).
+     * Storage backend for the persistent `anonymous_id` and `session_id`.
+     * Pass `AsyncStorage` from `@react-native-async-storage/async-storage`
+     * (recommended) or any object satisfying `AsyncStorageLike`. Omit /
+     * pass `null` for ephemeral in-memory ids that reset on every cold
+     * start.
+     *
+     * The SDK no longer auto-detects AsyncStorage as of 0.3.0 — the
+     * runtime require broke Metro bundling, and forcing every consumer
+     * to install an unused peer dep was the wrong trade. See CHANGELOG.
+     *
+     * ```ts
+     * import AsyncStorage from "@react-native-async-storage/async-storage";
+     * init({ apiKey, storage: AsyncStorage });
+     * ```
      */
     storage?: AsyncStorageLike | null;
     /**
@@ -70,6 +82,31 @@ interface InitOptions {
      * AppState; tests pass a stub.
      */
     appState?: AppStateLike | null;
+    /**
+     * Auto-capture unhandled JS errors via ErrorUtils.setGlobalHandler.
+     * Default true. Set false to disable (e.g. when another tool like Sentry
+     * already owns the global handler). When enabled, the SDK chains to any
+     * previously installed handler so RN's red-box and other reporters
+     * still fire.
+     *
+     * Native crashes (iOS / Android) are NOT captured — that requires native
+     * modules outside this SDK's scope.
+     */
+    captureUnhandledErrors?: boolean;
+    /**
+     * Override the global ErrorUtils-like object the SDK installs into.
+     * The SDK auto-detects React Native's ErrorUtils on globalThis at
+     * runtime; tests pass a stub.
+     */
+    errorUtils?: ErrorUtilsLike | null;
+}
+/**
+ * Minimal shape of React Native's ErrorUtils. The SDK uses these three
+ * methods to chain into any previously installed handler.
+ */
+interface ErrorUtilsLike {
+    setGlobalHandler(handler: (err: unknown, isFatal?: boolean) => void): void;
+    getGlobalHandler?(): ((err: unknown, isFatal?: boolean) => void) | undefined;
 }
 /**
  * Minimal AppState shape the SDK consumes (subset of react-native's AppState).
@@ -85,6 +122,13 @@ interface LuminClient {
     screen(name?: string, properties?: Record<string, unknown>): void;
     track(name: string, properties?: Record<string, unknown>): void;
     identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Capture an error. Accepts a real Error (preferred — preserves stack +
+     * constructor name as error_type), or any value that will be stringified
+     * for error_message. `properties` is forwarded verbatim so callers can
+     * attach context (route, user action, request id).
+     */
+    captureError(err: unknown, properties?: Record<string, unknown>): void;
     flush(): Promise<void>;
     close(): Promise<void>;
     /** Current session id. Resolves once AsyncStorage hydration finishes. */
@@ -93,4 +137,4 @@ interface LuminClient {
     getAnonymousId(): Promise<string>;
 }
 
-export type { AppStateLike as A, EventType as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a };
+export type { AppStateLike as A, ErrorUtilsLike as E, InitOptions as I, LuminClient as L, WireEvent as W, AsyncStorageLike as a, EventType as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumin-monitor/react-native",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "React Native SDK for Lumin: screen / track / identify with batched ingest.",
   "keywords": [
     "lumin",
@@ -50,18 +50,15 @@
   "files": [
     "dist",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@react-native-async-storage/async-storage": ">=1.21.0",
     "@react-navigation/native": ">=6",
     "react": ">=18",
     "react-native": ">=0.72"
   },
   "peerDependenciesMeta": {
-    "@react-native-async-storage/async-storage": {
-      "optional": true
-    },
     "@react-navigation/native": {
       "optional": true
     }

package/dist/chunk-3RG5ZIWI.js

@@ -1,10 +0,0 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
-export {
-  __require
-};