@logbrew/react-native 0.1.9 → 0.1.10

package/README.md

@@ -6,7 +6,7 @@
 
 React Native helpers for the public LogBrew JavaScript SDK.
 
-This package is intentionally thin. It keeps all event validation, retry, flush, and shutdown behavior in `@logbrew/sdk`, while adding mobile-friendly helpers for screen views, app-state changes, product actions, API milestones, handled JavaScript errors, app-owned Promise rejection reports, provider/hook usage, active W3C trace correlation, explicit W3C trace propagation, opt-in lifecycle spans, opt-in resource fetch spans, opt-in reversible global fetch spans, app-owned native bridge scope sync, and reversible instrumentation setup.
+This package is intentionally thin. It keeps all event validation, retry, flush, and shutdown behavior in `@logbrew/sdk`, while adding mobile-friendly helpers for screen views, app-state changes, product actions, API milestones, handled JavaScript errors, opt-in Hermes Promise rejection tracking, app-owned Promise rejection callbacks, provider/hook usage, active W3C trace correlation, explicit W3C trace propagation, opt-in lifecycle spans, opt-in resource fetch spans, opt-in reversible global fetch spans, app-owned native bridge scope sync, and reversible instrumentation setup.
 
 ## Install
 
@@ -202,7 +202,49 @@ Installation is idempotent for the active React Native `ErrorUtils` object. The
 
 The React Native conditional export obtains LogBrew's synchronous native fatal store through the supported TurboModule or `NativeModules` seam. Before chaining a fatal report, it writes one bounded record to app-private storage that is excluded from operating-system archives. On a later installation it performs stable-ID at-least-once replay, and acknowledgement happens only after local queue admission is observable through the SDK queue counters. Filtered, dropped, unknown-admission, persistence-failed, and acknowledgement-failed records are retained. A failed acknowledgement is retried without admitting the same ID twice in one JavaScript runtime. Use `fatalHealth()` for frozen bounded counters and status, or `discardPendingFatalRecord()` for an explicit rollback discard. The Node ESM and CommonJS entries never import React Native; non-React-Native callers must inject `fatalStore` explicitly.
 
-Automatic events exclude the original error message, raw stack, arbitrary metadata, full URLs, hosts, query strings, local absolute paths, payloads, and native error text. `onDiagnostic` receives only a fixed code. This integration does not claim mathematically exactly-once delivery, backend-visible deduplication, native crash capture, automatic Promise rejection tracker ownership, ANR or hang detection, general offline queueing, or symbolication.
+Automatic events exclude the original error message, raw stack, arbitrary metadata, full URLs, hosts, query strings, local absolute paths, payloads, and native error text. `onDiagnostic` receives only a fixed code. This integration does not claim mathematically exactly-once delivery, backend-visible deduplication, native crash capture, ANR or hang detection, general offline queueing, or symbolication.
+
+### Opt-in Hermes Promise rejection tracking
+
+React Native exposes one Promise rejection tracker slot. Claim it explicitly
+when LogBrew is the only tracker owner:
+
+```js
+import {
+  installLogBrewReactNativePromiseRejectionTracker
+} from "@logbrew/react-native";
+
+const promiseRejectionTracker =
+  installLogBrewReactNativePromiseRejectionTracker({
+    client,
+    takeOwnership: true,
+    onDiagnostic({ code }) {
+      console.warn(`LogBrew Promise rejection tracker: ${code}`);
+    }
+  });
+
+promiseRejectionTracker.health();
+promiseRejectionTracker.rejectionHealth();
+```
+
+The React Native export discovers the active Hermes runtime and uses its
+native tracker without replacing `globalThis.Promise`. Installation is
+idempotent for that runtime slot. It records fixed-content issues without
+reading the rejection value or emitting the runtime rejection identifier.
+`rejectionHealth()` returns bounded duplicate, eviction, and later-handled
+counters.
+
+Do not install this helper while Sentry or another integration owns the same
+tracker slot. Use the app-owned callback composition below when another
+integration must remain the owner. Hermes does not expose a previous-owner
+restoration API. `deactivate()` therefore stops LogBrew capture through its
+installed callbacks but cannot reinstate an earlier tracker. Install
+the replacement owner after deactivation when switching integrations.
+
+For JavaScriptCore or another runtime, pass an explicit `tracker` with an
+`enable(options)` function that already controls the Promise implementation
+used by the app. LogBrew does not replace the global Promise or add a hidden
+Promise polyfill.
 
 ### App-owned Promise rejection reports
 

package/global-errors.cjs

@@ -3,7 +3,8 @@
 const { createReactNativeErrorEvent } = require("./index.cjs");
 const { createFatalController } = require("./fatal-replay.cjs");
 const {
-  createLogBrewReactNativePromiseRejectionHandlers
+  createLogBrewReactNativePromiseRejectionHandlers,
+  installLogBrewReactNativePromiseRejectionTracker
 } = require("./promise-rejections.cjs");
 
 const AUTOMATIC_ERROR_MESSAGE = "React Native global JavaScript report";
@@ -412,7 +413,8 @@ function isObjectLike(value) {
 
 const defaultExport = {
   createLogBrewReactNativePromiseRejectionHandlers,
-  installLogBrewReactNativeGlobalErrorHandler
+  installLogBrewReactNativeGlobalErrorHandler,
+  installLogBrewReactNativePromiseRejectionTracker
 };
 
 module.exports = { ...defaultExport, default: defaultExport };

package/global-errors.d.cts

@@ -14,6 +14,9 @@ export type ReactNativePromiseRejectionDiagnosticCode =
   | "promise_rejection_handler_unavailable"
   | "promise_rejection_id_unavailable"
   | "promise_rejection_recursive_capture_suppressed"
+  | "promise_rejection_tracker_installation_failed"
+  | "promise_rejection_tracker_ownership_required"
+  | "promise_rejection_tracker_unavailable"
   | "promise_rejection_tracking_evicted";
 
 export type ReactNativePromiseRejectionDiagnostic = Readonly<{
@@ -96,6 +99,54 @@ export type LogBrewReactNativePromiseRejectionHandlers = Readonly<{
   onUnhandled(runtimeRejectionId: unknown, rejection?: unknown): void;
 }>;
 
+export type ReactNativePromiseRejectionTrackerLike = {
+  enable(options: Readonly<{
+    allRejections: true;
+    onHandled(runtimeRejectionId: unknown): void;
+    onUnhandled(runtimeRejectionId: unknown, rejection?: unknown): void;
+  }>): void;
+};
+
+export type InstallLogBrewReactNativePromiseRejectionTrackerOptions = {
+  client: Pick<LogBrewClient, "issue">;
+  /**
+   * Confirms that LogBrew may claim the runtime's single Promise rejection
+   * tracker slot. Do not install another tracker owner at the same time.
+   */
+  takeOwnership: true;
+  /**
+   * Optional tracker seam. The React Native conditional export discovers the
+   * active Hermes tracker when this is omitted.
+   */
+  tracker?: ReactNativePromiseRejectionTrackerLike;
+  maxTrackedRejections?: number;
+  onDiagnostic?: (diagnostic: ReactNativePromiseRejectionDiagnostic) => void;
+};
+
+export type ReactNativePromiseRejectionTrackerHealth = Readonly<{
+  active: boolean;
+  available: boolean;
+  engine: "custom" | "hermes" | "unavailable";
+  lastOutcome:
+    | "deactivated"
+    | "handler_unavailable"
+    | "installation_failed"
+    | "installed"
+    | "ownership_required"
+    | "tracker_unavailable";
+  restoration: "deactivate_only";
+}>;
+
+export type LogBrewReactNativePromiseRejectionTrackerInstallation = Readonly<{
+  /**
+   * Stops LogBrew capture through the installed callbacks. Hermes does not
+   * expose a previous-owner restoration API, so this cannot restore one.
+   */
+  deactivate(): boolean;
+  health(): ReactNativePromiseRejectionTrackerHealth;
+  rejectionHealth(): ReactNativePromiseRejectionHealth;
+}>;
+
 export type ReactNativeFatalRecord = Readonly<{
   corruptRecords: number;
   droppedRecords: number;
@@ -175,6 +226,17 @@ export declare function createLogBrewReactNativePromiseRejectionHandlers(
   options: CreateLogBrewReactNativePromiseRejectionHandlersOptions
 ): LogBrewReactNativePromiseRejectionHandlers;
 
+/**
+ * Install privacy-safe automatic Promise rejection capture.
+ *
+ * Installation is opt-in because React Native runtimes expose one tracker slot.
+ * The React Native conditional export discovers Hermes without replacing the
+ * global Promise. Other runtimes can inject a compatible tracker explicitly.
+ */
+export declare function installLogBrewReactNativePromiseRejectionTracker(
+  options: InstallLogBrewReactNativePromiseRejectionTrackerOptions
+): LogBrewReactNativePromiseRejectionTrackerInstallation;
+
 /**
  * Install reversible automatic capture for React Native global JavaScript errors.
  *
@@ -190,6 +252,7 @@ export declare function installLogBrewReactNativeGlobalErrorHandler(
 declare const logBrewReactNativeGlobalErrors: {
   createLogBrewReactNativePromiseRejectionHandlers: typeof createLogBrewReactNativePromiseRejectionHandlers;
   installLogBrewReactNativeGlobalErrorHandler: typeof installLogBrewReactNativeGlobalErrorHandler;
+  installLogBrewReactNativePromiseRejectionTracker: typeof installLogBrewReactNativePromiseRejectionTracker;
 };
 
 export default logBrewReactNativeGlobalErrors;

package/global-errors.d.ts

@@ -14,6 +14,9 @@ export type ReactNativePromiseRejectionDiagnosticCode =
   | "promise_rejection_handler_unavailable"
   | "promise_rejection_id_unavailable"
   | "promise_rejection_recursive_capture_suppressed"
+  | "promise_rejection_tracker_installation_failed"
+  | "promise_rejection_tracker_ownership_required"
+  | "promise_rejection_tracker_unavailable"
   | "promise_rejection_tracking_evicted";
 
 export type ReactNativePromiseRejectionDiagnostic = Readonly<{
@@ -96,6 +99,54 @@ export type LogBrewReactNativePromiseRejectionHandlers = Readonly<{
   onUnhandled(runtimeRejectionId: unknown, rejection?: unknown): void;
 }>;
 
+export type ReactNativePromiseRejectionTrackerLike = {
+  enable(options: Readonly<{
+    allRejections: true;
+    onHandled(runtimeRejectionId: unknown): void;
+    onUnhandled(runtimeRejectionId: unknown, rejection?: unknown): void;
+  }>): void;
+};
+
+export type InstallLogBrewReactNativePromiseRejectionTrackerOptions = {
+  client: Pick<LogBrewClient, "issue">;
+  /**
+   * Confirms that LogBrew may claim the runtime's single Promise rejection
+   * tracker slot. Do not install another tracker owner at the same time.
+   */
+  takeOwnership: true;
+  /**
+   * Optional tracker seam. The React Native conditional export discovers the
+   * active Hermes tracker when this is omitted.
+   */
+  tracker?: ReactNativePromiseRejectionTrackerLike;
+  maxTrackedRejections?: number;
+  onDiagnostic?: (diagnostic: ReactNativePromiseRejectionDiagnostic) => void;
+};
+
+export type ReactNativePromiseRejectionTrackerHealth = Readonly<{
+  active: boolean;
+  available: boolean;
+  engine: "custom" | "hermes" | "unavailable";
+  lastOutcome:
+    | "deactivated"
+    | "handler_unavailable"
+    | "installation_failed"
+    | "installed"
+    | "ownership_required"
+    | "tracker_unavailable";
+  restoration: "deactivate_only";
+}>;
+
+export type LogBrewReactNativePromiseRejectionTrackerInstallation = Readonly<{
+  /**
+   * Stops LogBrew capture through the installed callbacks. Hermes does not
+   * expose a previous-owner restoration API, so this cannot restore one.
+   */
+  deactivate(): boolean;
+  health(): ReactNativePromiseRejectionTrackerHealth;
+  rejectionHealth(): ReactNativePromiseRejectionHealth;
+}>;
+
 export type ReactNativeFatalRecord = Readonly<{
   corruptRecords: number;
   droppedRecords: number;
@@ -175,6 +226,17 @@ export declare function createLogBrewReactNativePromiseRejectionHandlers(
   options: CreateLogBrewReactNativePromiseRejectionHandlersOptions
 ): LogBrewReactNativePromiseRejectionHandlers;
 
+/**
+ * Install privacy-safe automatic Promise rejection capture.
+ *
+ * Installation is opt-in because React Native runtimes expose one tracker slot.
+ * The React Native conditional export discovers Hermes without replacing the
+ * global Promise. Other runtimes can inject a compatible tracker explicitly.
+ */
+export declare function installLogBrewReactNativePromiseRejectionTracker(
+  options: InstallLogBrewReactNativePromiseRejectionTrackerOptions
+): LogBrewReactNativePromiseRejectionTrackerInstallation;
+
 /**
  * Install reversible automatic capture for React Native global JavaScript errors.
  *
@@ -190,6 +252,7 @@ export declare function installLogBrewReactNativeGlobalErrorHandler(
 declare const logBrewReactNativeGlobalErrors: {
   createLogBrewReactNativePromiseRejectionHandlers: typeof createLogBrewReactNativePromiseRejectionHandlers;
   installLogBrewReactNativeGlobalErrorHandler: typeof installLogBrewReactNativeGlobalErrorHandler;
+  installLogBrewReactNativePromiseRejectionTracker: typeof installLogBrewReactNativePromiseRejectionTracker;
 };
 
 export default logBrewReactNativeGlobalErrors;

package/global-errors.js

@@ -2,7 +2,8 @@ import implementation from "./global-errors.cjs";
 
 export const {
   createLogBrewReactNativePromiseRejectionHandlers,
-  installLogBrewReactNativeGlobalErrorHandler
+  installLogBrewReactNativeGlobalErrorHandler,
+  installLogBrewReactNativePromiseRejectionTracker
 } = implementation;
 
 export default implementation;

package/global-errors.native.js

@@ -2,13 +2,16 @@ import { NativeModules, TurboModuleRegistry } from "react-native";
 
 import {
   createLogBrewReactNativePromiseRejectionHandlers,
-  installLogBrewReactNativeGlobalErrorHandler as installPlatformNeutralHandler
+  installLogBrewReactNativeGlobalErrorHandler as installPlatformNeutralHandler,
+  installLogBrewReactNativePromiseRejectionTracker as installPlatformNeutralTracker
 } from "./global-errors.js";
 
 export {
   createLogBrewReactNativePromiseRejectionHandlers
 };
 
+const hermesTrackerAdapters = new WeakMap();
+
 function defaultFatalStore() {
   try {
     return TurboModuleRegistry?.get?.("LogBrewFatalStore")
@@ -18,6 +21,40 @@ function defaultFatalStore() {
   }
 }
 
+function defaultPromiseRejectionTracker() {
+  let hermes;
+  let enable;
+  let hasPromise;
+  try {
+    hermes = globalThis?.HermesInternal;
+    if (hermes === null
+      || (typeof hermes !== "object" && typeof hermes !== "function")) {
+      return undefined;
+    }
+    enable = hermes.enablePromiseRejectionTracker;
+    hasPromise = hermes.hasPromise;
+    if (typeof enable !== "function"
+      || typeof hasPromise !== "function"
+      || hasPromise.call(hermes) !== true) {
+      return undefined;
+    }
+  } catch {
+    return undefined;
+  }
+
+  const existing = hermesTrackerAdapters.get(hermes);
+  if (existing) {
+    return existing;
+  }
+  const adapter = Object.freeze({
+    enable(options) {
+      return enable.call(hermes, options);
+    }
+  });
+  hermesTrackerAdapters.set(hermes, adapter);
+  return adapter;
+}
+
 export function installLogBrewReactNativeGlobalErrorHandler(options = {}) {
   let forwarded;
   let hasInjectedStore = false;
@@ -37,9 +74,33 @@ export function installLogBrewReactNativeGlobalErrorHandler(options = {}) {
   });
 }
 
+export function installLogBrewReactNativePromiseRejectionTracker(options = {}) {
+  let forwarded;
+  let hasInjectedTracker = false;
+  try {
+    const input = options !== null
+      && (typeof options === "object" || typeof options === "function")
+      ? options
+      : {};
+    hasInjectedTracker = Object.prototype.hasOwnProperty.call(input, "tracker");
+    forwarded = { ...input };
+  } catch {
+    forwarded = {};
+  }
+  const tracker = hasInjectedTracker
+    ? forwarded.tracker
+    : defaultPromiseRejectionTracker();
+  return installPlatformNeutralTracker({
+    ...forwarded,
+    tracker,
+    trackerKind: hasInjectedTracker ? "custom" : tracker ? "hermes" : undefined
+  });
+}
+
 const logBrewReactNativeGlobalErrors = {
   createLogBrewReactNativePromiseRejectionHandlers,
-  installLogBrewReactNativeGlobalErrorHandler
+  installLogBrewReactNativeGlobalErrorHandler,
+  installLogBrewReactNativePromiseRejectionTracker
 };
 
 export default logBrewReactNativeGlobalErrors;

package/index.native.d.ts

@@ -1,2 +1,5 @@
 export * from "./index";
-export { installLogBrewReactNativeGlobalErrorHandler } from "./global-errors";
+export {
+  installLogBrewReactNativeGlobalErrorHandler,
+  installLogBrewReactNativePromiseRejectionTracker
+} from "./global-errors";

package/index.native.js

@@ -10,7 +10,8 @@ import {
   getReactNativeContext
 } from "./index.js";
 export {
-  installLogBrewReactNativeGlobalErrorHandler
+  installLogBrewReactNativeGlobalErrorHandler,
+  installLogBrewReactNativePromiseRejectionTracker
 } from "./global-errors.native.js";
 
 export * from "./index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/react-native",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "React Native screen, error, trace, action, and network timeline helpers for LogBrew.",
   "type": "module",
   "main": "./index.cjs",

package/promise-rejections.cjs

@@ -6,9 +6,17 @@ const AUTOMATIC_MESSAGE = "Unhandled Promise rejection";
 const DEFAULT_MAX_TRACKED_REJECTIONS = 128;
 const MAX_TRACKED_REJECTIONS = 1024;
 const MAX_STRING_ID_LENGTH = 128;
+const activeTrackerInstallations = new WeakMap();
 let nextEventSequence = 0;
 
 function createLogBrewReactNativePromiseRejectionHandlers(options = {}) {
+  return createPromiseRejectionHandlers(
+    options,
+    "app_owned_promise_rejection_tracker"
+  );
+}
+
+function createPromiseRejectionHandlers(options, mechanism) {
   const input = isObjectLike(options) ? options : {};
   const client = safeReadProperty(input, "client");
   const issue = safeFunction(client, "issue");
@@ -92,7 +100,7 @@ function createLogBrewReactNativePromiseRejectionHandlers(options = {}) {
         if (key === undefined) {
           emitStateDiagnostic(state, onDiagnostic, "promise_rejection_id_unavailable");
         }
-        const event = createEvent();
+        const event = createEvent(mechanism);
         issue.call(client, event.id, event.timestamp, event.attributes);
         state.capturedEvents = incrementBounded(state.capturedEvents);
 
@@ -124,7 +132,93 @@ function createLogBrewReactNativePromiseRejectionHandlers(options = {}) {
   });
 }
 
-function createEvent() {
+function installLogBrewReactNativePromiseRejectionTracker(options = {}) {
+  const input = isObjectLike(options) ? options : {};
+  const onDiagnostic = safeFunction(input, "onDiagnostic");
+  if (safeReadProperty(input, "takeOwnership") !== true) {
+    emitDiagnostic(onDiagnostic, "promise_rejection_tracker_ownership_required");
+    return inactiveTrackerInstallation("ownership_required");
+  }
+
+  const tracker = safeReadProperty(input, "tracker");
+  const enable = safeFunction(tracker, "enable");
+  const engine = safeReadProperty(input, "trackerKind") === "hermes"
+    ? "hermes"
+    : isObjectLike(tracker) ? "custom" : "unavailable";
+  if (!isObjectLike(tracker) || !enable) {
+    emitDiagnostic(onDiagnostic, "promise_rejection_tracker_unavailable");
+    return inactiveTrackerInstallation("tracker_unavailable", engine);
+  }
+
+  const existing = activeTrackerInstallations.get(tracker);
+  if (existing?.health().active) {
+    return existing;
+  }
+
+  const handlers = createPromiseRejectionHandlers(
+    input,
+    "logbrew_owned_promise_rejection_tracker"
+  );
+  if (!handlers.health().available) {
+    return inactiveTrackerInstallation("handler_unavailable", engine, handlers);
+  }
+
+  const state = {
+    active: true,
+    lastOutcome: "installed"
+  };
+  const trackerOptions = Object.freeze({
+    allRejections: true,
+    onHandled(runtimeRejectionId) {
+      if (state.active) {
+        handlers.onHandled(runtimeRejectionId);
+      }
+    },
+    onUnhandled(runtimeRejectionId, rejection) {
+      if (state.active) {
+        handlers.onUnhandled(runtimeRejectionId, rejection);
+      }
+    }
+  });
+
+  const installation = Object.freeze({
+    deactivate() {
+      if (!state.active) {
+        return false;
+      }
+      state.active = false;
+      state.lastOutcome = "deactivated";
+      if (activeTrackerInstallations.get(tracker) === installation) {
+        activeTrackerInstallations.delete(tracker);
+      }
+      return true;
+    },
+    health() {
+      return trackerHealthSnapshot(state, engine, true);
+    },
+    rejectionHealth() {
+      return handlers.health();
+    }
+  });
+
+  try {
+    enable.call(tracker, trackerOptions);
+  } catch {
+    state.active = false;
+    state.lastOutcome = "installation_failed";
+    emitDiagnostic(onDiagnostic, "promise_rejection_tracker_installation_failed");
+    return inactiveTrackerInstallation(
+      "installation_failed",
+      engine,
+      handlers
+    );
+  }
+
+  activeTrackerInstallations.set(tracker, installation);
+  return installation;
+}
+
+function createEvent(mechanism) {
   const error = new Error(AUTOMATIC_MESSAGE);
   delete error.stack;
   const event = createReactNativeErrorEvent(error, {
@@ -142,7 +236,7 @@ function createEvent() {
         automatic: true,
         fatal: false,
         handled: false,
-        mechanism: "app_owned_promise_rejection_tracker",
+        mechanism,
         source: "react-native.promise_rejection"
       }
     }
@@ -224,6 +318,35 @@ function inactiveHandlers() {
   });
 }
 
+function inactiveTrackerInstallation(
+  lastOutcome,
+  engine = "unavailable",
+  handlers = inactiveHandlers()
+) {
+  const snapshot = Object.freeze({
+    active: false,
+    available: false,
+    engine,
+    lastOutcome,
+    restoration: "deactivate_only"
+  });
+  return Object.freeze({
+    deactivate: () => false,
+    health: () => snapshot,
+    rejectionHealth: () => handlers.health()
+  });
+}
+
+function trackerHealthSnapshot(state, engine, available) {
+  return Object.freeze({
+    active: state.active,
+    available,
+    engine,
+    lastOutcome: state.lastOutcome,
+    restoration: "deactivate_only"
+  });
+}
+
 function healthSnapshot(state, trackedRejections, maxTrackedRejections) {
   return Object.freeze({
     available: true,
@@ -267,5 +390,6 @@ function isObjectLike(value) {
 }
 
 module.exports = {
-  createLogBrewReactNativePromiseRejectionHandlers
+  createLogBrewReactNativePromiseRejectionHandlers,
+  installLogBrewReactNativePromiseRejectionTracker
 };