@logbrew/react-native 0.1.5 → 0.1.7

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, 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, 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.
 
 ## Install
 
@@ -22,27 +22,96 @@ import { AppState, Platform } from "react-native";
 import {
   captureScreenView,
   createAppStateListener,
-  createLogBrewReactNativeClient
+  createLogBrewReactNativeClient,
+  createReactNativeFetchTransport
 } from "@logbrew/react-native";
 
+// Expo example. Bare React Native apps can use the same public key from
+// their app-owned configuration layer.
+const clientKey = process.env.EXPO_PUBLIC_LOGBREW_CLIENT_KEY;
+if (!clientKey) {
+  throw new Error("Set EXPO_PUBLIC_LOGBREW_CLIENT_KEY to the public app-scoped key");
+}
+
 const client = createLogBrewReactNativeClient({
-  clientKey: "LOGBREW_CLIENT_KEY",
+  clientKey,
   sdkName: "my-mobile-app",
-  sdkVersion: "0.1.0"
+  sdkVersion: "0.1.0",
+  transport: createReactNativeFetchTransport()
 });
 
 captureScreenView(client, "Checkout", {
   platform: Platform,
-  appState: AppState,
-  timestamp: "2026-06-02T10:00:03Z"
+  appState: AppState
 });
 
 const stopListening = createAppStateListener(client, AppState, {
+  flushOnBackground: true,
   platform: Platform
 });
+
+export async function verifyLogBrewSetup() {
+  const timestamp = new Date().toISOString();
+  client.log(`evt_react_native_setup_${Date.now()}`, timestamp, {
+    level: "info",
+    message: "React Native setup check",
+    metadata: {
+      environment: __DEV__ ? "development" : "production",
+      service: "my-mobile-app"
+    }
+  });
+
+  const receipt = await client.flush();
+  return {
+    delivery: "hosted_accepted",
+    statusCode: receipt.statusCode,
+    attempts: receipt.attempts,
+    batches: receipt.batches
+  };
+}
 ```
 
-For mobile apps, prefer an app-scoped public key through `clientKey`. `apiKey` is still accepted for compatibility with lower-level SDK examples.
+For mobile apps, prefer an app-scoped public key through `clientKey`. Expo
+inlines `EXPO_PUBLIC_*` values into the app, so never use a server key there.
+`apiKey` is still accepted for compatibility with lower-level SDK examples.
+
+Supplying `transport` enables the core SDK's bounded automatic delivery. It
+coalesces concurrent work, retries transient failures, retains rejected
+batches, and pauses repeated automatic sends after authentication, rate-limit,
+or non-retryable failures. Do not add a second app-owned flush interval.
+`flushOnBackground: true` requests one final flush when AppState becomes
+`inactive` or `background`; a failure never escapes the AppState callback.
+
+## Confirm Hosted Delivery And Event Visibility
+
+Call `verifyLogBrewSetup()` once from a development-only button or setup
+screen. A returned `hosted_accepted` receipt means the configured HTTPS intake
+accepted every batch in that flush. Then use an authenticated CLI session to
+confirm that the backend stored the event for the intended project:
+
+```bash
+logbrew read logs --project <project_id> \
+  --search "React Native setup check" --since 1h --json
+```
+
+These checks have different meanings:
+
+- `client.previewJson()` validates and displays the local queued payload.
+- `RecordingTransport.alwaysAccept()` is a local recording transport. Its
+  synthetic HTTP `202` makes no network request and never indicates hosted
+  delivery.
+- `createReactNativeFetchTransport()` returns the actual intake status to
+  `client.flush()`.
+- An authenticated CLI read confirms that the accepted event is visible in the
+  selected project. An intake `2xx` alone does not confirm event visibility.
+
+Use `client.deliveryHealth()` for content-free queue and delivery state. In
+particular, inspect `deliveryState`, `lastOutcome`, `lastStatusClass`,
+`pausedReason`, `queueEvents`, and `acceptedEvents`. A `401` pauses automatic
+delivery with `pausedReason: "authentication"`; rotate or correct the public
+client key before creating a new client. A `429` preserves the queue and
+reports `pausedReason: "rate_limit"` plus the bounded retry signal exposed by
+the failed flush.
 
 ## Product Actions And API Milestones
 
@@ -128,7 +197,37 @@ 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, Promise rejection ownership, ANR or hang detection, general offline queueing, or symbolication. Unhandled Promise rejections are not installed or patched because React Native does not expose one stable supported ownership seam across its runtimes.
+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.
+
+### App-owned Promise rejection reports
+
+Use the Promise rejection callbacks when your app or framework already owns rejection tracking:
+
+```js
+import {
+  createLogBrewReactNativePromiseRejectionHandlers
+} from "@logbrew/react-native/global-errors";
+
+const logBrewPromiseRejections =
+  createLogBrewReactNativePromiseRejectionHandlers({
+    client,
+    onDiagnostic({ code }) {
+      console.warn(`LogBrew Promise rejection handler: ${code}`);
+    }
+  });
+
+const promiseRejectionTrackerOptions = {
+  allRejections: true,
+  onUnhandled: logBrewPromiseRejections.onUnhandled,
+  onHandled: logBrewPromiseRejections.onHandled
+};
+
+// Pass promiseRejectionTrackerOptions to the tracker your app already owns.
+```
+
+The callbacks match the common `(id, rejection)` and `(id)` tracker shapes, but LogBrew does not install, replace, or patch Promise, Hermes, JavaScriptCore, or a global rejection tracker. If another integration already has callbacks, keep that integration as the tracker owner and call both callback sets from the app-owned composition point.
+
+`onUnhandled()` emits a fixed-content issue and deliberately does not inspect or send the rejection value, raw runtime rejection ID, error message, stack, Promise, or arbitrary metadata. Numeric IDs and bounded strings are retained only in local memory for duplicate suppression and `onHandled()` health. The set defaults to 128 entries and can be configured from 1 to 1024 with `maxTrackedRejections`; old entries are evicted. Missing or unsafe IDs still produce an untracked privacy-safe report. `onHandled()` updates local health only and cannot retract an issue that was already queued. Use `health()` for frozen counters and the last bounded outcome. Capture and diagnostic failures never escape these callbacks.
 
 When you prepare React Native release artifacts, wrap the app-owned Metro config once. Production bundles and source maps receive one matching Debug ID, while development and hot-reload serialization remain unchanged:
 

package/examples/readme-example.mjs

@@ -28,7 +28,14 @@ captureScreenView(client, "Checkout", {
 
 console.log(client.previewJson());
 const response = await client.shutdown(RecordingTransport.alwaysAccept());
-console.error(JSON.stringify({ ok: true, status: response.statusCode, attempts: response.attempts, events: 6 }));
+console.error(JSON.stringify({
+  ok: true,
+  mode: "local_recording",
+  hostedAccepted: false,
+  status: response.statusCode,
+  attempts: response.attempts,
+  events: 6
+}));
 
 function addFullBatch(client) {
   client.release("evt_release_001", "2026-06-02T10:00:00Z", {

package/global-errors.cjs

@@ -2,6 +2,9 @@
 
 const { createReactNativeErrorEvent } = require("./index.cjs");
 const { createFatalController } = require("./fatal-replay.cjs");
+const {
+  createLogBrewReactNativePromiseRejectionHandlers
+} = require("./promise-rejections.cjs");
 
 const AUTOMATIC_ERROR_MESSAGE = "React Native global JavaScript report";
 const MAX_STACK_BYTES = 16 * 1024;
@@ -408,6 +411,7 @@ function isObjectLike(value) {
 }
 
 const defaultExport = {
+  createLogBrewReactNativePromiseRejectionHandlers,
   installLogBrewReactNativeGlobalErrorHandler
 };
 

package/global-errors.d.cts

@@ -7,6 +7,19 @@ export type ReactNativeErrorUtilsLike = {
   setGlobalHandler(handler: ReactNativeGlobalErrorHandler | undefined): void;
 };
 
+export type ReactNativePromiseRejectionDiagnosticCode =
+  | "promise_rejection_capture_failed"
+  | "promise_rejection_configuration_invalid"
+  | "promise_rejection_duplicate_suppressed"
+  | "promise_rejection_handler_unavailable"
+  | "promise_rejection_id_unavailable"
+  | "promise_rejection_recursive_capture_suppressed"
+  | "promise_rejection_tracking_evicted";
+
+export type ReactNativePromiseRejectionDiagnostic = Readonly<{
+  code: ReactNativePromiseRejectionDiagnosticCode;
+}>;
+
 export type ReactNativeGlobalErrorDiagnosticCode =
   | "capture_failed"
   | "duplicate_capture_suppressed"
@@ -44,6 +57,45 @@ export type ReactNativeGlobalErrorHealth = Readonly<{
   suppressedEvents: number;
 }>;
 
+export type ReactNativePromiseRejectionHealth = Readonly<{
+  available: boolean;
+  capturedEvents: number;
+  evictedRejections: number;
+  handledLaterEvents: number;
+  lastOutcome:
+    | "capture_failed"
+    | "captured"
+    | "captured_untracked"
+    | "captured_with_eviction"
+    | "duplicate_suppressed"
+    | "handled_later"
+    | "handled_unknown"
+    | "idle"
+    | "recursive_suppressed"
+    | "unavailable";
+  maxTrackedRejections: number;
+  suppressedEvents: number;
+  trackedRejections: number;
+  unknownHandledEvents: number;
+  untrackedEvents: number;
+}>;
+
+export type CreateLogBrewReactNativePromiseRejectionHandlersOptions = {
+  client: Pick<LogBrewClient, "issue">;
+  /**
+   * Maximum number of safe runtime rejection identifiers retained for duplicate
+   * suppression and later-handled health. Defaults to 128 and must be 1-1024.
+   */
+  maxTrackedRejections?: number;
+  onDiagnostic?: (diagnostic: ReactNativePromiseRejectionDiagnostic) => void;
+};
+
+export type LogBrewReactNativePromiseRejectionHandlers = Readonly<{
+  health(): ReactNativePromiseRejectionHealth;
+  onHandled(runtimeRejectionId: unknown): void;
+  onUnhandled(runtimeRejectionId: unknown, rejection?: unknown): void;
+}>;
+
 export type ReactNativeFatalRecord = Readonly<{
   corruptRecords: number;
   droppedRecords: number;
@@ -112,6 +164,17 @@ export type LogBrewReactNativeGlobalErrorHandlerInstallation = Readonly<{
   remove(): boolean;
 }>;
 
+/**
+ * Create privacy-safe callbacks for a Promise rejection tracker owned by the app.
+ *
+ * The callbacks do not install or patch Promise, Hermes, JavaScriptCore, or globals.
+ * Automatic reports never inspect or emit the rejection value or runtime identifier.
+ * Tracking is bounded and suppresses duplicate callbacks only while an identifier is retained.
+ */
+export declare function createLogBrewReactNativePromiseRejectionHandlers(
+  options: CreateLogBrewReactNativePromiseRejectionHandlersOptions
+): LogBrewReactNativePromiseRejectionHandlers;
+
 /**
  * Install reversible automatic capture for React Native global JavaScript errors.
  *
@@ -125,6 +188,7 @@ export declare function installLogBrewReactNativeGlobalErrorHandler(
 ): LogBrewReactNativeGlobalErrorHandlerInstallation;
 
 declare const logBrewReactNativeGlobalErrors: {
+  createLogBrewReactNativePromiseRejectionHandlers: typeof createLogBrewReactNativePromiseRejectionHandlers;
   installLogBrewReactNativeGlobalErrorHandler: typeof installLogBrewReactNativeGlobalErrorHandler;
 };
 

package/global-errors.d.ts

@@ -7,6 +7,19 @@ export type ReactNativeErrorUtilsLike = {
   setGlobalHandler(handler: ReactNativeGlobalErrorHandler | undefined): void;
 };
 
+export type ReactNativePromiseRejectionDiagnosticCode =
+  | "promise_rejection_capture_failed"
+  | "promise_rejection_configuration_invalid"
+  | "promise_rejection_duplicate_suppressed"
+  | "promise_rejection_handler_unavailable"
+  | "promise_rejection_id_unavailable"
+  | "promise_rejection_recursive_capture_suppressed"
+  | "promise_rejection_tracking_evicted";
+
+export type ReactNativePromiseRejectionDiagnostic = Readonly<{
+  code: ReactNativePromiseRejectionDiagnosticCode;
+}>;
+
 export type ReactNativeGlobalErrorDiagnosticCode =
   | "capture_failed"
   | "duplicate_capture_suppressed"
@@ -44,6 +57,45 @@ export type ReactNativeGlobalErrorHealth = Readonly<{
   suppressedEvents: number;
 }>;
 
+export type ReactNativePromiseRejectionHealth = Readonly<{
+  available: boolean;
+  capturedEvents: number;
+  evictedRejections: number;
+  handledLaterEvents: number;
+  lastOutcome:
+    | "capture_failed"
+    | "captured"
+    | "captured_untracked"
+    | "captured_with_eviction"
+    | "duplicate_suppressed"
+    | "handled_later"
+    | "handled_unknown"
+    | "idle"
+    | "recursive_suppressed"
+    | "unavailable";
+  maxTrackedRejections: number;
+  suppressedEvents: number;
+  trackedRejections: number;
+  unknownHandledEvents: number;
+  untrackedEvents: number;
+}>;
+
+export type CreateLogBrewReactNativePromiseRejectionHandlersOptions = {
+  client: Pick<LogBrewClient, "issue">;
+  /**
+   * Maximum number of safe runtime rejection identifiers retained for duplicate
+   * suppression and later-handled health. Defaults to 128 and must be 1-1024.
+   */
+  maxTrackedRejections?: number;
+  onDiagnostic?: (diagnostic: ReactNativePromiseRejectionDiagnostic) => void;
+};
+
+export type LogBrewReactNativePromiseRejectionHandlers = Readonly<{
+  health(): ReactNativePromiseRejectionHealth;
+  onHandled(runtimeRejectionId: unknown): void;
+  onUnhandled(runtimeRejectionId: unknown, rejection?: unknown): void;
+}>;
+
 export type ReactNativeFatalRecord = Readonly<{
   corruptRecords: number;
   droppedRecords: number;
@@ -112,6 +164,17 @@ export type LogBrewReactNativeGlobalErrorHandlerInstallation = Readonly<{
   remove(): boolean;
 }>;
 
+/**
+ * Create privacy-safe callbacks for a Promise rejection tracker owned by the app.
+ *
+ * The callbacks do not install or patch Promise, Hermes, JavaScriptCore, or globals.
+ * Automatic reports never inspect or emit the rejection value or runtime identifier.
+ * Tracking is bounded and suppresses duplicate callbacks only while an identifier is retained.
+ */
+export declare function createLogBrewReactNativePromiseRejectionHandlers(
+  options: CreateLogBrewReactNativePromiseRejectionHandlersOptions
+): LogBrewReactNativePromiseRejectionHandlers;
+
 /**
  * Install reversible automatic capture for React Native global JavaScript errors.
  *
@@ -125,6 +188,7 @@ export declare function installLogBrewReactNativeGlobalErrorHandler(
 ): LogBrewReactNativeGlobalErrorHandlerInstallation;
 
 declare const logBrewReactNativeGlobalErrors: {
+  createLogBrewReactNativePromiseRejectionHandlers: typeof createLogBrewReactNativePromiseRejectionHandlers;
   installLogBrewReactNativeGlobalErrorHandler: typeof installLogBrewReactNativeGlobalErrorHandler;
 };
 

package/global-errors.js

@@ -1,6 +1,7 @@
 import implementation from "./global-errors.cjs";
 
 export const {
+  createLogBrewReactNativePromiseRejectionHandlers,
   installLogBrewReactNativeGlobalErrorHandler
 } = implementation;
 

package/global-errors.native.js

@@ -1,9 +1,14 @@
 import { NativeModules, TurboModuleRegistry } from "react-native";
 
 import {
+  createLogBrewReactNativePromiseRejectionHandlers,
   installLogBrewReactNativeGlobalErrorHandler as installPlatformNeutralHandler
 } from "./global-errors.js";
 
+export {
+  createLogBrewReactNativePromiseRejectionHandlers
+};
+
 function defaultFatalStore() {
   try {
     return TurboModuleRegistry?.get?.("LogBrewFatalStore")
@@ -33,6 +38,7 @@ export function installLogBrewReactNativeGlobalErrorHandler(options = {}) {
 }
 
 const logBrewReactNativeGlobalErrors = {
+  createLogBrewReactNativePromiseRejectionHandlers,
   installLogBrewReactNativeGlobalErrorHandler
 };
 

package/index.cjs

@@ -4,7 +4,8 @@ const {
   createTraceparent,
   LogBrewClient,
   parseTraceparent,
-  SdkError
+  SdkError,
+  TransportError
 } = require("@logbrew/sdk");
 const {
   runtimeReactNativeDebugIdMap,
@@ -14,22 +15,83 @@ const {
 
 const DEFAULT_SDK_NAME = "logbrew-react-native";
 const DEFAULT_SDK_VERSION = "0.1.0";
+const DEFAULT_ENDPOINT = "https://api.logbrew.co/v1/events";
+const BACKGROUND_APP_STATES = new Set(["background", "inactive"]);
 const LogBrewNativeContext = React.createContext(null);
 const activeTraceScopes = [];
 let nextTraceScopeId = 0;
 
 function createLogBrewReactNativeClient({
+  automaticDelivery,
   apiKey,
   clientKey,
+  deliveryIntervalMs,
+  deliveryQueueThreshold,
+  maxBatchBytes,
+  maxBatchEvents,
+  maxQueueBytes,
+  maxQueueSize,
+  onEventDropped,
   sdkName = DEFAULT_SDK_NAME,
   sdkVersion = DEFAULT_SDK_VERSION,
-  maxRetries = 2
+  maxRetries = 2,
+  transport
 }) {
   const authKey = clientKey ?? apiKey;
   if (!authKey) {
     throw new SdkError("configuration_error", "createLogBrewReactNativeClient requires clientKey or apiKey");
   }
-  return LogBrewClient.create({ apiKey: authKey, sdkName, sdkVersion, maxRetries });
+  return LogBrewClient.create({
+    apiKey: authKey,
+    automaticDelivery,
+    deliveryIntervalMs,
+    deliveryQueueThreshold,
+    maxBatchBytes,
+    maxBatchEvents,
+    maxQueueBytes,
+    maxQueueSize,
+    maxRetries,
+    onEventDropped,
+    sdkName,
+    sdkVersion,
+    transport
+  });
+}
+
+function createReactNativeFetchTransport({
+  endpoint = DEFAULT_ENDPOINT,
+  fetchImpl = defaultFetch(),
+  headers = {}
+} = {}) {
+  validateDeliveryEndpoint(endpoint);
+  if (typeof fetchImpl !== "function") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport requires fetch");
+  }
+  if (!headers || Array.isArray(headers) || typeof headers !== "object") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport headers must be an object");
+  }
+
+  return Object.freeze({
+    async send(apiKey, body) {
+      try {
+        const response = await fetchImpl(endpoint, {
+          body,
+          headers: {
+            ...headers,
+            authorization: `Bearer ${apiKey}`,
+            "content-type": "application/json"
+          },
+          method: "POST"
+        });
+        const retryAfterMs = retryAfterMsFromHeaders(response?.headers);
+        return retryAfterMs === undefined
+          ? { statusCode: response?.status, attempts: 1 }
+          : { statusCode: response?.status, attempts: 1, retryAfterMs };
+      } catch {
+        throw TransportError.network("LogBrew React Native delivery failed");
+      }
+    }
+  });
 }
 
 function createReactNativeTraceparent({ randomValues = defaultRandomValues, spanId, traceFlags = "01", traceId } = {}) {
@@ -574,12 +636,34 @@ function createAppStateListener(client, appState, options = {}) {
   if (!appState || typeof appState.addEventListener !== "function") {
     throw new SdkError("configuration_error", "createAppStateListener requires AppState.addEventListener");
   }
+  const {
+    flushOnBackground = false,
+    onFlushError,
+    ...captureOptions
+  } = options;
+  if (typeof flushOnBackground !== "boolean") {
+    throw new SdkError("configuration_error", "createAppStateListener flushOnBackground must be a boolean");
+  }
+  if (onFlushError !== undefined && typeof onFlushError !== "function") {
+    throw new SdkError("configuration_error", "createAppStateListener onFlushError must be a function");
+  }
 
   const subscription = appState.addEventListener("change", (nextState) => {
     captureAppStateChange(client, nextState, {
-      ...options,
+      ...captureOptions,
       appState
     });
+    if (flushOnBackground && BACKGROUND_APP_STATES.has(nextState)) {
+      void client.flush().catch((error) => {
+        if (typeof onFlushError === "function") {
+          try {
+            onFlushError(error);
+          } catch {
+            // Delivery diagnostics must not interrupt the app-state callback.
+          }
+        }
+      });
+    }
   });
 
   return subscriptionRemover(subscription);
@@ -616,6 +700,9 @@ function useLogBrewNativeActions() {
     action: (id, timestamp, attributes) => client.action(id, timestamp, attributesWithTrace(attributes, trace)),
     flush: client.flush.bind(client),
     shutdown: client.shutdown.bind(client),
+    deliveryHealth: client.deliveryHealth.bind(client),
+    droppedEvents: client.droppedEvents.bind(client),
+    pendingBytes: client.pendingBytes.bind(client),
     previewJson: client.previewJson.bind(client),
     pendingEvents: client.pendingEvents.bind(client),
     trace,
@@ -699,6 +786,44 @@ function errorMessage(error) {
   return String(error ?? "unknown error");
 }
 
+function validateDeliveryEndpoint(endpoint) {
+  if (typeof endpoint !== "string" || endpoint.trim() === "") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport requires a non-empty endpoint");
+  }
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport endpoint must be an absolute URL");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport endpoint must use HTTPS");
+  }
+  if (endpoint !== `${parsed.origin}${parsed.pathname}`) {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport endpoint must be a plain HTTPS path");
+  }
+}
+
+function retryAfterMsFromHeaders(headers) {
+  if (!headers || typeof headers.get !== "function") {
+    return undefined;
+  }
+  return retryAfterMsFromHeader(headers.get("retry-after"));
+}
+
+function retryAfterMsFromHeader(value, now = Date.now()) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (/^\d+$/u.test(trimmed)) {
+    const milliseconds = Number(trimmed) * 1000;
+    return Number.isSafeInteger(milliseconds) ? milliseconds : undefined;
+  }
+  const timestamp = Date.parse(trimmed);
+  return Number.isFinite(timestamp) ? Math.max(0, timestamp - now) : undefined;
+}
+
 function defaultErrorEventId({ message, screen }) {
   return `evt_native_error_${slugify(`${screen ?? "app"}_${message}`)}`;
 }
@@ -977,7 +1102,8 @@ const defaultExport = {
   LogBrewNativeProvider, captureAppStateChange, captureReactNativeAction, captureReactNativeError,
   captureReactNativeNetwork, captureReactNativeNavigationSpan, captureReactNativeResourceSpan, captureScreenView,
   bindLogBrewTrace, createAppStateListener, createLogBrewReactNativeClient, createReactNavigationSpanListener,
-  createReactNativeSpanAttributes, createReactNativeTraceContext, createReactNativeTraceHeaders, createReactNativeActionEvent,
+  createReactNativeFetchTransport, createReactNativeSpanAttributes, createReactNativeTraceContext,
+  createReactNativeTraceHeaders, createReactNativeActionEvent,
   createReactNativeErrorEvent, createReactNativeNetworkEvent, createReactNativeNavigationSpanEvent,
   createReactNativeResourceSpanEvent, createReactNativeTraceparent, createTraceparentFetch, getActiveLogBrewTrace,
   getReactNativeContext, getReactNativeTraceMetadata, shouldPropagateTraceparent, useLogBrewNative,

package/index.d.cts

@@ -1,6 +1,8 @@
 import type * as React from "react";
 import type {
   ActionAttributes,
+  DeliveryHealthSnapshot,
+  DroppedEvent,
   EnvironmentAttributes,
   IssueAttributes,
   LogAttributes,
@@ -30,11 +32,42 @@ export type ReactNativeAppStateLike = {
 };
 
 export type CreateLogBrewReactNativeClientConfig = {
+  automaticDelivery?: boolean;
   apiKey?: string;
   clientKey?: string;
+  deliveryIntervalMs?: number;
+  deliveryQueueThreshold?: number;
+  maxBatchBytes?: number;
+  maxBatchEvents?: number;
+  maxQueueBytes?: number;
+  maxQueueSize?: number;
+  maxRetries?: number;
+  onEventDropped?: (drop: DroppedEvent) => void;
   sdkName?: string;
   sdkVersion?: string;
-  maxRetries?: number;
+  transport?: Transport;
+};
+
+export type ReactNativeFetchResponseLike = {
+  status: number;
+  headers?: {
+    get(name: string): string | null | undefined;
+  };
+};
+
+export type ReactNativeFetchLike = (
+  endpoint: string,
+  init: {
+    body: string;
+    headers: Record<string, string>;
+    method: "POST";
+  }
+) => Promise<ReactNativeFetchResponseLike> | ReactNativeFetchResponseLike;
+
+export type ReactNativeFetchTransportConfig = {
+  endpoint?: string;
+  fetchImpl?: ReactNativeFetchLike;
+  headers?: Record<string, string>;
 };
 
 export type TracePropagationTarget = string | RegExp | ((url: string) => boolean);
@@ -122,6 +155,13 @@ export type CaptureAppStateChangeOptions = ReactNativeContextOptions & {
   timestamp?: string;
 };
 
+export type CreateAppStateListenerOptions = CaptureAppStateChangeOptions & {
+  /** Flush the configured client transport when AppState becomes inactive or background. */
+  flushOnBackground?: boolean;
+  /** Observe a background flush failure without throwing from the AppState callback. */
+  onFlushError?: (error: unknown) => void;
+};
+
 export type ReactNativeActionEvent = {
   id: string;
   timestamp: string;
@@ -278,8 +318,11 @@ export type LogBrewNativeActions = {
   log(id: string, timestamp: string, attributes: LogAttributes): void;
   span(id: string, timestamp: string, attributes: SpanAttributes): void;
   action(id: string, timestamp: string, attributes: ActionAttributes): void;
-  flush(transport: Transport): Promise<TransportResponse>;
-  shutdown(transport: Transport): Promise<TransportResponse>;
+  flush(transport?: Transport): Promise<TransportResponse>;
+  shutdown(transport?: Transport): Promise<TransportResponse>;
+  deliveryHealth(): DeliveryHealthSnapshot;
+  droppedEvents(): number;
+  pendingBytes(): number;
   previewJson(): string;
   pendingEvents(): number;
   trace?: ReactNativeTraceContext;
@@ -295,6 +338,9 @@ export type LogBrewNativeActions = {
 export declare function createLogBrewReactNativeClient(
   config: CreateLogBrewReactNativeClientConfig
 ): LogBrewClient;
+export declare function createReactNativeFetchTransport(
+  config?: ReactNativeFetchTransportConfig
+): Transport;
 export declare function createReactNativeTraceparent(config?: ReactNativeTraceparentConfig): string;
 export declare function createReactNativeTraceContext(
   config?: ReactNativeTraceContextConfig
@@ -378,7 +424,7 @@ export declare function captureReactNativeError(
 export declare function createAppStateListener(
   client: LogBrewClient,
   appState: ReactNativeAppStateLike,
-  options?: CaptureAppStateChangeOptions
+  options?: CreateAppStateListenerOptions
 ): () => void;
 export declare function LogBrewNativeProvider(props: LogBrewNativeProviderProps): React.ReactElement;
 export declare function useLogBrewNative(): LogBrewNativeContextValue;
@@ -413,7 +459,7 @@ export declare function captureDefaultReactNativeError(
 ): ReactNativeErrorEvent;
 export declare function createDefaultAppStateListener(
   client: LogBrewClient,
-  options?: Omit<CaptureAppStateChangeOptions, "appState">
+  options?: Omit<CreateAppStateListenerOptions, "appState">
 ): () => void;
 
 declare const defaultExport: {
@@ -429,6 +475,7 @@ declare const defaultExport: {
   createAppStateListener: typeof createAppStateListener;
   createLogBrewReactNativeClient: typeof createLogBrewReactNativeClient;
   createReactNavigationSpanListener: typeof createReactNavigationSpanListener;
+  createReactNativeFetchTransport: typeof createReactNativeFetchTransport;
   createReactNativeSpanAttributes: typeof createReactNativeSpanAttributes;
   createReactNativeTraceContext: typeof createReactNativeTraceContext;
   createReactNativeTraceHeaders: typeof createReactNativeTraceHeaders;

package/index.d.ts

@@ -1,6 +1,8 @@
 import type * as React from "react";
 import type {
   ActionAttributes,
+  DeliveryHealthSnapshot,
+  DroppedEvent,
   EnvironmentAttributes,
   IssueAttributes,
   LogAttributes,
@@ -30,11 +32,42 @@ export type ReactNativeAppStateLike = {
 };
 
 export type CreateLogBrewReactNativeClientConfig = {
+  automaticDelivery?: boolean;
   apiKey?: string;
   clientKey?: string;
+  deliveryIntervalMs?: number;
+  deliveryQueueThreshold?: number;
+  maxBatchBytes?: number;
+  maxBatchEvents?: number;
+  maxQueueBytes?: number;
+  maxQueueSize?: number;
+  maxRetries?: number;
+  onEventDropped?: (drop: DroppedEvent) => void;
   sdkName?: string;
   sdkVersion?: string;
-  maxRetries?: number;
+  transport?: Transport;
+};
+
+export type ReactNativeFetchResponseLike = {
+  status: number;
+  headers?: {
+    get(name: string): string | null | undefined;
+  };
+};
+
+export type ReactNativeFetchLike = (
+  endpoint: string,
+  init: {
+    body: string;
+    headers: Record<string, string>;
+    method: "POST";
+  }
+) => Promise<ReactNativeFetchResponseLike> | ReactNativeFetchResponseLike;
+
+export type ReactNativeFetchTransportConfig = {
+  endpoint?: string;
+  fetchImpl?: ReactNativeFetchLike;
+  headers?: Record<string, string>;
 };
 
 export type TracePropagationTarget = string | RegExp | ((url: string) => boolean);
@@ -122,6 +155,13 @@ export type CaptureAppStateChangeOptions = ReactNativeContextOptions & {
   timestamp?: string;
 };
 
+export type CreateAppStateListenerOptions = CaptureAppStateChangeOptions & {
+  /** Flush the configured client transport when AppState becomes inactive or background. */
+  flushOnBackground?: boolean;
+  /** Observe a background flush failure without throwing from the AppState callback. */
+  onFlushError?: (error: unknown) => void;
+};
+
 export type ReactNativeActionEvent = {
   id: string;
   timestamp: string;
@@ -278,8 +318,11 @@ export type LogBrewNativeActions = {
   log(id: string, timestamp: string, attributes: LogAttributes): void;
   span(id: string, timestamp: string, attributes: SpanAttributes): void;
   action(id: string, timestamp: string, attributes: ActionAttributes): void;
-  flush(transport: Transport): Promise<TransportResponse>;
-  shutdown(transport: Transport): Promise<TransportResponse>;
+  flush(transport?: Transport): Promise<TransportResponse>;
+  shutdown(transport?: Transport): Promise<TransportResponse>;
+  deliveryHealth(): DeliveryHealthSnapshot;
+  droppedEvents(): number;
+  pendingBytes(): number;
   previewJson(): string;
   pendingEvents(): number;
   trace?: ReactNativeTraceContext;
@@ -295,6 +338,9 @@ export type LogBrewNativeActions = {
 export declare function createLogBrewReactNativeClient(
   config: CreateLogBrewReactNativeClientConfig
 ): LogBrewClient;
+export declare function createReactNativeFetchTransport(
+  config?: ReactNativeFetchTransportConfig
+): Transport;
 export declare function createReactNativeTraceparent(config?: ReactNativeTraceparentConfig): string;
 export declare function createReactNativeTraceContext(
   config?: ReactNativeTraceContextConfig
@@ -378,7 +424,7 @@ export declare function captureReactNativeError(
 export declare function createAppStateListener(
   client: LogBrewClient,
   appState: ReactNativeAppStateLike,
-  options?: CaptureAppStateChangeOptions
+  options?: CreateAppStateListenerOptions
 ): () => void;
 export declare function LogBrewNativeProvider(props: LogBrewNativeProviderProps): React.ReactElement;
 export declare function useLogBrewNative(): LogBrewNativeContextValue;
@@ -413,7 +459,7 @@ export declare function captureDefaultReactNativeError(
 ): ReactNativeErrorEvent;
 export declare function createDefaultAppStateListener(
   client: LogBrewClient,
-  options?: Omit<CaptureAppStateChangeOptions, "appState">
+  options?: Omit<CreateAppStateListenerOptions, "appState">
 ): () => void;
 
 declare const defaultExport: {
@@ -429,6 +475,7 @@ declare const defaultExport: {
   createAppStateListener: typeof createAppStateListener;
   createLogBrewReactNativeClient: typeof createLogBrewReactNativeClient;
   createReactNavigationSpanListener: typeof createReactNavigationSpanListener;
+  createReactNativeFetchTransport: typeof createReactNativeFetchTransport;
   createReactNativeSpanAttributes: typeof createReactNativeSpanAttributes;
   createReactNativeTraceContext: typeof createReactNativeTraceContext;
   createReactNativeTraceHeaders: typeof createReactNativeTraceHeaders;

package/index.js

@@ -4,7 +4,8 @@ import {
   createTraceparent,
   LogBrewClient,
   parseTraceparent,
-  SdkError
+  SdkError,
+  TransportError
 } from "@logbrew/sdk";
 import {
   runtimeReactNativeDebugIdMap,
@@ -14,22 +15,83 @@ import {
 
 const DEFAULT_SDK_NAME = "logbrew-react-native";
 const DEFAULT_SDK_VERSION = "0.1.0";
+const DEFAULT_ENDPOINT = "https://api.logbrew.co/v1/events";
+const BACKGROUND_APP_STATES = new Set(["background", "inactive"]);
 const LogBrewNativeContext = React.createContext(null);
 const activeTraceScopes = [];
 let nextTraceScopeId = 0;
 
 export function createLogBrewReactNativeClient({
+  automaticDelivery,
   apiKey,
   clientKey,
+  deliveryIntervalMs,
+  deliveryQueueThreshold,
+  maxBatchBytes,
+  maxBatchEvents,
+  maxQueueBytes,
+  maxQueueSize,
+  onEventDropped,
   sdkName = DEFAULT_SDK_NAME,
   sdkVersion = DEFAULT_SDK_VERSION,
-  maxRetries = 2
+  maxRetries = 2,
+  transport
 }) {
   const authKey = clientKey ?? apiKey;
   if (!authKey) {
     throw new SdkError("configuration_error", "createLogBrewReactNativeClient requires clientKey or apiKey");
   }
-  return LogBrewClient.create({ apiKey: authKey, sdkName, sdkVersion, maxRetries });
+  return LogBrewClient.create({
+    apiKey: authKey,
+    automaticDelivery,
+    deliveryIntervalMs,
+    deliveryQueueThreshold,
+    maxBatchBytes,
+    maxBatchEvents,
+    maxQueueBytes,
+    maxQueueSize,
+    maxRetries,
+    onEventDropped,
+    sdkName,
+    sdkVersion,
+    transport
+  });
+}
+
+export function createReactNativeFetchTransport({
+  endpoint = DEFAULT_ENDPOINT,
+  fetchImpl = defaultFetch(),
+  headers = {}
+} = {}) {
+  validateDeliveryEndpoint(endpoint);
+  if (typeof fetchImpl !== "function") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport requires fetch");
+  }
+  if (!headers || Array.isArray(headers) || typeof headers !== "object") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport headers must be an object");
+  }
+
+  return Object.freeze({
+    async send(apiKey, body) {
+      try {
+        const response = await fetchImpl(endpoint, {
+          body,
+          headers: {
+            ...headers,
+            authorization: `Bearer ${apiKey}`,
+            "content-type": "application/json"
+          },
+          method: "POST"
+        });
+        const retryAfterMs = retryAfterMsFromHeaders(response?.headers);
+        return retryAfterMs === undefined
+          ? { statusCode: response?.status, attempts: 1 }
+          : { statusCode: response?.status, attempts: 1, retryAfterMs };
+      } catch {
+        throw TransportError.network("LogBrew React Native delivery failed");
+      }
+    }
+  });
 }
 
 export function createReactNativeTraceparent({ randomValues = defaultRandomValues, spanId, traceFlags = "01", traceId } = {}) {
@@ -563,12 +625,34 @@ export function createAppStateListener(client, appState, options = {}) {
   if (!appState || typeof appState.addEventListener !== "function") {
     throw new SdkError("configuration_error", "createAppStateListener requires AppState.addEventListener");
   }
+  const {
+    flushOnBackground = false,
+    onFlushError,
+    ...captureOptions
+  } = options;
+  if (typeof flushOnBackground !== "boolean") {
+    throw new SdkError("configuration_error", "createAppStateListener flushOnBackground must be a boolean");
+  }
+  if (onFlushError !== undefined && typeof onFlushError !== "function") {
+    throw new SdkError("configuration_error", "createAppStateListener onFlushError must be a function");
+  }
 
   const subscription = appState.addEventListener("change", (nextState) => {
     captureAppStateChange(client, nextState, {
-      ...options,
+      ...captureOptions,
       appState
     });
+    if (flushOnBackground && BACKGROUND_APP_STATES.has(nextState)) {
+      void client.flush().catch((error) => {
+        if (typeof onFlushError === "function") {
+          try {
+            onFlushError(error);
+          } catch {
+            // Delivery diagnostics must not interrupt the app-state callback.
+          }
+        }
+      });
+    }
   });
 
   return subscriptionRemover(subscription);
@@ -605,6 +689,9 @@ export function useLogBrewNativeActions() {
     action: (id, timestamp, attributes) => client.action(id, timestamp, attributesWithTrace(attributes, trace)),
     flush: client.flush.bind(client),
     shutdown: client.shutdown.bind(client),
+    deliveryHealth: client.deliveryHealth.bind(client),
+    droppedEvents: client.droppedEvents.bind(client),
+    pendingBytes: client.pendingBytes.bind(client),
     previewJson: client.previewJson.bind(client),
     pendingEvents: client.pendingEvents.bind(client),
     trace,
@@ -688,6 +775,44 @@ function errorMessage(error) {
   return String(error ?? "unknown error");
 }
 
+function validateDeliveryEndpoint(endpoint) {
+  if (typeof endpoint !== "string" || endpoint.trim() === "") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport requires a non-empty endpoint");
+  }
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport endpoint must be an absolute URL");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport endpoint must use HTTPS");
+  }
+  if (endpoint !== `${parsed.origin}${parsed.pathname}`) {
+    throw new SdkError("configuration_error", "createReactNativeFetchTransport endpoint must be a plain HTTPS path");
+  }
+}
+
+function retryAfterMsFromHeaders(headers) {
+  if (!headers || typeof headers.get !== "function") {
+    return undefined;
+  }
+  return retryAfterMsFromHeader(headers.get("retry-after"));
+}
+
+function retryAfterMsFromHeader(value, now = Date.now()) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (/^\d+$/u.test(trimmed)) {
+    const milliseconds = Number(trimmed) * 1000;
+    return Number.isSafeInteger(milliseconds) ? milliseconds : undefined;
+  }
+  const timestamp = Date.parse(trimmed);
+  return Number.isFinite(timestamp) ? Math.max(0, timestamp - now) : undefined;
+}
+
 function defaultErrorEventId({ message, screen }) {
   return `evt_native_error_${slugify(`${screen ?? "app"}_${message}`)}`;
 }
@@ -966,7 +1091,8 @@ export default {
   LogBrewNativeProvider, captureAppStateChange, captureReactNativeAction, captureReactNativeError,
   captureReactNativeNetwork, captureReactNativeNavigationSpan, captureReactNativeResourceSpan, captureScreenView,
   bindLogBrewTrace, createAppStateListener, createLogBrewReactNativeClient, createReactNavigationSpanListener,
-  createReactNativeSpanAttributes, createReactNativeTraceContext, createReactNativeTraceHeaders, createReactNativeActionEvent,
+  createReactNativeFetchTransport, createReactNativeSpanAttributes, createReactNativeTraceContext,
+  createReactNativeTraceHeaders, createReactNativeActionEvent,
   createReactNativeErrorEvent, createReactNativeNetworkEvent, createReactNativeNavigationSpanEvent,
   createReactNativeResourceSpanEvent, createReactNativeTraceparent, createTraceparentFetch, getActiveLogBrewTrace,
   getReactNativeContext, getReactNativeTraceMetadata, shouldPropagateTraceparent, useLogBrewNative,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/react-native",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "React Native screen, error, trace, action, and network timeline helpers for LogBrew.",
   "type": "module",
   "main": "./index.cjs",
@@ -136,6 +136,7 @@
     "lifecycle.d.ts",
     "lifecycle.d.cts",
     "global-errors.cjs",
+    "promise-rejections.cjs",
     "fatal-replay.cjs",
     "global-errors.js",
     "global-errors.native.js",
@@ -207,6 +208,6 @@
     "react-native": ">=0.72"
   },
   "scripts": {
-    "test": "node --check index.js && node --check index.cjs && node --check index.native.js && node --check apollo.js && node --check apollo.cjs && node --check instrumentation.js && node --check instrumentation.cjs && node --check lifecycle.js && node --check lifecycle.cjs && node --check global-errors.js && node --check global-errors.native.js && node --check global-errors.cjs && node --check fatal-replay.cjs && node --check metadata.js && node --check metadata.cjs && node --check native-bridge.js && node --check native-bridge.cjs && node --check resource-fetch.js && node --check resource-fetch.cjs && node --check release-artifacts.js && node --check release-artifacts.cjs && node --check metro.js && node --check metro.cjs && node --check examples/index.mjs && node --check examples/apollo-link-spans.mjs && node --check examples/instrumentation-kit.mjs && node --check examples/lifecycle-spans.mjs && node --check examples/native-bridge-scope.mjs && node --check examples/navigation-resource-spans.mjs && node --check examples/readme-example.mjs && node --check examples/real-user-smoke.mjs && node --check examples/resource-fetch-spans.mjs && node --check examples/trace-correlation.mjs && node --test"
+    "test": "node --check index.js && node --check index.cjs && node --check index.native.js && node --check apollo.js && node --check apollo.cjs && node --check instrumentation.js && node --check instrumentation.cjs && node --check lifecycle.js && node --check lifecycle.cjs && node --check global-errors.js && node --check global-errors.native.js && node --check global-errors.cjs && node --check promise-rejections.cjs && node --check fatal-replay.cjs && node --check metadata.js && node --check metadata.cjs && node --check native-bridge.js && node --check native-bridge.cjs && node --check resource-fetch.js && node --check resource-fetch.cjs && node --check release-artifacts.js && node --check release-artifacts.cjs && node --check metro.js && node --check metro.cjs && node --check examples/index.mjs && node --check examples/apollo-link-spans.mjs && node --check examples/instrumentation-kit.mjs && node --check examples/lifecycle-spans.mjs && node --check examples/native-bridge-scope.mjs && node --check examples/navigation-resource-spans.mjs && node --check examples/readme-example.mjs && node --check examples/real-user-smoke.mjs && node --check examples/resource-fetch-spans.mjs && node --check examples/trace-correlation.mjs && node --test"
   }
 }

package/promise-rejections.cjs

@@ -0,0 +1,271 @@
+"use strict";
+
+const { createReactNativeErrorEvent } = require("./index.cjs");
+
+const AUTOMATIC_MESSAGE = "Unhandled Promise rejection";
+const DEFAULT_MAX_TRACKED_REJECTIONS = 128;
+const MAX_TRACKED_REJECTIONS = 1024;
+const MAX_STRING_ID_LENGTH = 128;
+let nextEventSequence = 0;
+
+function createLogBrewReactNativePromiseRejectionHandlers(options = {}) {
+  const input = isObjectLike(options) ? options : {};
+  const client = safeReadProperty(input, "client");
+  const issue = safeFunction(client, "issue");
+  const onDiagnostic = safeFunction(input, "onDiagnostic");
+  if (!issue) {
+    emitDiagnostic(onDiagnostic, "promise_rejection_handler_unavailable");
+    return inactiveHandlers();
+  }
+
+  const configuredMaximum = safeReadProperty(input, "maxTrackedRejections");
+  const maxTrackedRejections = validMaximum(configuredMaximum)
+    ? configuredMaximum
+    : DEFAULT_MAX_TRACKED_REJECTIONS;
+  if (configuredMaximum !== undefined && maxTrackedRejections !== configuredMaximum) {
+    emitDiagnostic(onDiagnostic, "promise_rejection_configuration_invalid");
+  }
+
+  const tracked = new Map();
+  const state = {
+    capturedEvents: 0,
+    emittingDiagnostic: false,
+    evictedRejections: 0,
+    handledLaterEvents: 0,
+    handling: false,
+    lastOutcome: "idle",
+    suppressedEvents: 0,
+    unknownHandledEvents: 0,
+    untrackedEvents: 0
+  };
+  let emittedEvictionDiagnostic = false;
+
+  return Object.freeze({
+    health() {
+      return healthSnapshot(state, tracked.size, maxTrackedRejections);
+    },
+    onHandled(runtimeRejectionId) {
+      const key = rejectionKey(runtimeRejectionId);
+      const record = key === undefined ? undefined : tracked.get(key);
+      if (!record) {
+        state.unknownHandledEvents = incrementBounded(state.unknownHandledEvents);
+        state.lastOutcome = "handled_unknown";
+        return;
+      }
+      if (record.handled) {
+        recordSuppression(
+          state,
+          onDiagnostic,
+          "promise_rejection_duplicate_suppressed",
+          "duplicate_suppressed"
+        );
+        return;
+      }
+      record.handled = true;
+      state.handledLaterEvents = incrementBounded(state.handledLaterEvents);
+      state.lastOutcome = "handled_later";
+    },
+    onUnhandled(runtimeRejectionId) {
+      if (state.handling) {
+        recordSuppression(
+          state,
+          onDiagnostic,
+          "promise_rejection_recursive_capture_suppressed",
+          "recursive_suppressed"
+        );
+        return;
+      }
+
+      const key = rejectionKey(runtimeRejectionId);
+      if (key !== undefined && tracked.has(key)) {
+        recordSuppression(
+          state,
+          onDiagnostic,
+          "promise_rejection_duplicate_suppressed",
+          "duplicate_suppressed"
+        );
+        return;
+      }
+
+      state.handling = true;
+      try {
+        if (key === undefined) {
+          emitStateDiagnostic(state, onDiagnostic, "promise_rejection_id_unavailable");
+        }
+        const event = createEvent();
+        issue.call(client, event.id, event.timestamp, event.attributes);
+        state.capturedEvents = incrementBounded(state.capturedEvents);
+
+        if (key === undefined) {
+          state.untrackedEvents = incrementBounded(state.untrackedEvents);
+          state.lastOutcome = "captured_untracked";
+          return;
+        }
+
+        let evicted = false;
+        if (tracked.size === maxTrackedRejections) {
+          tracked.delete(tracked.keys().next().value);
+          state.evictedRejections = incrementBounded(state.evictedRejections);
+          evicted = true;
+          if (!emittedEvictionDiagnostic) {
+            emittedEvictionDiagnostic = true;
+            emitStateDiagnostic(state, onDiagnostic, "promise_rejection_tracking_evicted");
+          }
+        }
+        tracked.set(key, { handled: false });
+        state.lastOutcome = evicted ? "captured_with_eviction" : "captured";
+      } catch {
+        state.lastOutcome = "capture_failed";
+        emitStateDiagnostic(state, onDiagnostic, "promise_rejection_capture_failed");
+      } finally {
+        state.handling = false;
+      }
+    }
+  });
+}
+
+function createEvent() {
+  const error = new Error(AUTOMATIC_MESSAGE);
+  delete error.stack;
+  const event = createReactNativeErrorEvent(error, {
+    id: nextEventId(),
+    includeStack: false
+  });
+  return {
+    ...event,
+    attributes: {
+      ...event.attributes,
+      title: AUTOMATIC_MESSAGE,
+      message: AUTOMATIC_MESSAGE,
+      metadata: {
+        ...event.attributes.metadata,
+        automatic: true,
+        fatal: false,
+        handled: false,
+        mechanism: "app_owned_promise_rejection_tracker",
+        source: "react-native.promise_rejection"
+      }
+    }
+  };
+}
+
+function rejectionKey(value) {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    return `number:${value}`;
+  }
+  if (typeof value === "string"
+    && value.length > 0
+    && value.length <= MAX_STRING_ID_LENGTH
+    && !hasControlCharacter(value)) {
+    return `string:${value}`;
+  }
+  return undefined;
+}
+
+function validMaximum(value) {
+  return Number.isInteger(value) && value >= 1 && value <= MAX_TRACKED_REJECTIONS;
+}
+
+function nextEventId() {
+  nextEventSequence = incrementBounded(nextEventSequence);
+  return `evt_rn_promise_${Date.now().toString(36)}_${nextEventSequence.toString(36)}`;
+}
+
+function incrementBounded(value) {
+  return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + 1;
+}
+
+function recordSuppression(state, onDiagnostic, code, outcome) {
+  state.suppressedEvents = incrementBounded(state.suppressedEvents);
+  state.lastOutcome = outcome;
+  emitStateDiagnostic(state, onDiagnostic, code);
+}
+
+function emitStateDiagnostic(state, onDiagnostic, code) {
+  if (state.emittingDiagnostic) {
+    return;
+  }
+  state.emittingDiagnostic = true;
+  try {
+    emitDiagnostic(onDiagnostic, code);
+  } finally {
+    state.emittingDiagnostic = false;
+  }
+}
+
+function emitDiagnostic(onDiagnostic, code) {
+  if (typeof onDiagnostic !== "function") {
+    return;
+  }
+  try {
+    onDiagnostic(Object.freeze({ code }));
+  } catch {
+    // Diagnostics must never interfere with application rejection handling.
+  }
+}
+
+function inactiveHandlers() {
+  const snapshot = Object.freeze({
+    available: false,
+    capturedEvents: 0,
+    evictedRejections: 0,
+    handledLaterEvents: 0,
+    lastOutcome: "unavailable",
+    maxTrackedRejections: 0,
+    suppressedEvents: 0,
+    trackedRejections: 0,
+    unknownHandledEvents: 0,
+    untrackedEvents: 0
+  });
+  return Object.freeze({
+    health: () => snapshot,
+    onHandled: () => {},
+    onUnhandled: () => {}
+  });
+}
+
+function healthSnapshot(state, trackedRejections, maxTrackedRejections) {
+  return Object.freeze({
+    available: true,
+    capturedEvents: state.capturedEvents,
+    evictedRejections: state.evictedRejections,
+    handledLaterEvents: state.handledLaterEvents,
+    lastOutcome: state.lastOutcome,
+    maxTrackedRejections,
+    suppressedEvents: state.suppressedEvents,
+    trackedRejections,
+    unknownHandledEvents: state.unknownHandledEvents,
+    untrackedEvents: state.untrackedEvents
+  });
+}
+
+function safeReadProperty(value, property) {
+  if (!isObjectLike(value)) {
+    return undefined;
+  }
+  try {
+    return value[property];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeFunction(value, property) {
+  const candidate = safeReadProperty(value, property);
+  return typeof candidate === "function" ? candidate : undefined;
+}
+
+function hasControlCharacter(value) {
+  return Array.from(value).some((character) => {
+    const code = character.codePointAt(0);
+    return code !== undefined && (code <= 31 || code === 127);
+  });
+}
+
+function isObjectLike(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function");
+}
+
+module.exports = {
+  createLogBrewReactNativePromiseRejectionHandlers
+};