@logbrew/react-native 0.1.6 → 0.1.8

package/README.md

@@ -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`. 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
 ```
 
-For mobile apps, prefer an app-scoped public key through `clientKey`. `apiKey` is still accepted for compatibility with lower-level SDK examples.
+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
 
@@ -160,7 +229,30 @@ The callbacks match the common `(id, rejection)` and `(id)` tracker shapes, but
 
 `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:
+When you prepare Expo release artifacts, create the Expo Metro config through
+LogBrew. The helper uses Expo's pre-serialization hook, so each production
+bundle receives Expo's final Debug ID before Hermes compilation. Apply
+the React Native Worklets bundle-mode transform after
+`getLogBrewExpoConfig()`, as shown:
+
+```js
+// metro.config.js
+const { getLogBrewExpoConfig } = require("@logbrew/react-native/metro");
+const { getBundleModeMetroConfig } = require("react-native-worklets/bundleMode");
+
+const config = getLogBrewExpoConfig(__dirname);
+
+module.exports = getBundleModeMetroConfig(config);
+```
+
+Pass normal Expo Metro options directly to the helper. If the app owns a
+custom `getDefaultConfig` function, pass it as the `getDefaultConfig` option.
+Existing `unstable_beforeAssetSerializationPlugins` are preserved and run
+before LogBrew's plugin.
+
+Bare React Native apps should instead wrap the completed app-owned Metro
+config once. Production bundles and source maps receive one matching Debug ID,
+while development and hot-reload serialization remain unchanged:
 
 ```js
 // metro.config.js
@@ -172,6 +264,11 @@ module.exports = withLogBrewMetroConfig(
 );
 ```
 
+Do not apply `withLogBrewMetroConfig()` to an Expo config. Expo static exports
+return asset sets and can produce Hermes bytecode; the bare React Native
+serializer wrapper stops with a recovery message that points to
+`getLogBrewExpoConfig()` rather than producing an untraceable build.
+
 Then use the same release identity when capturing the error. The Metro-injected runtime registry connects each matching parsed JavaScript frame to its Debug ID without another app option:
 
 ```js
@@ -186,7 +283,18 @@ captureReactNativeError(client, error, {
 });
 ```
 
-The wrapper composes an existing custom serializer, is idempotent, and adds no network behavior. A string-returning custom serializer may preserve Metro's default bundle code; a serializer that changes code must return `{ code, map }` so LogBrew cannot attach a mismatched source map. If an advanced build pipeline cannot use the wrapper, `debugIdMap` remains an explicit override and takes precedence over runtime discovery. LogBrew records up to 32 ordered path-only generated frames with matching Debug IDs, release/environment/service/runtime, and active trace IDs when available. It strips query strings, hashes, hosts, and local absolute paths from React Native frame data; raw stack text is still opt-in with `includeStack: true`. Hosted source-map lookup remains backend-owned and requires the matching uploaded release artifact.
+The Expo helper and bare wrapper add no network behavior. The bare wrapper
+composes an existing custom serializer and is idempotent. A string-returning
+custom serializer may preserve Metro's default bundle code; a serializer that
+changes code must return `{ code, map }` so LogBrew cannot attach a mismatched
+source map. If an advanced build pipeline cannot use either integration,
+`debugIdMap` remains an explicit override and takes precedence over runtime
+discovery. LogBrew records up to 32 ordered path-only generated frames with
+matching Debug IDs, release/environment/service/runtime, and active trace IDs
+when available. It strips query strings, hashes, hosts, and local absolute
+paths from React Native frame data; raw stack text is still opt-in with
+`includeStack: true`. Hosted source-map lookup remains backend-owned and
+requires the matching uploaded release artifact.
 
 ## Provider And Hooks
 

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/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/metro.cjs

@@ -2,12 +2,15 @@
 
 const crypto = require("node:crypto");
 const { Buffer } = require("node:buffer");
+const { createRequire } = require("node:module");
+const path = require("node:path");
 
 const DEBUG_ID_PLACEHOLDER = "__LOGBREW_REACT_NATIVE_DEBUG_ID__";
 const DEBUG_ID_MODULE_PATH = "__logbrew_debug_id__";
 const DEBUG_ID_REGISTRY_NAME = "@logbrew/react-native/debug-ids";
 const DEBUG_ID_KEYS = ["debug_id", "debugId", "debugID", "x_debug_id"];
 const DEBUG_ID_COMMENT_RE = /(?:\/\/[#@]|\/\*[#@])\s*debugId=[^\r\n]*/iu;
+const DEBUG_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const SOURCE_MAPPING_COMMENT_RE = /(?:\/\/[#@]|\/\*[#@])\s*sourceMappingURL=[^\r\n]*/giu;
 const WRAPPED_SERIALIZER = Symbol.for("@logbrew/react-native/metro-serializer");
 
@@ -35,8 +38,8 @@ function countLines(source) {
   return source === "" ? 0 : source.split("\n").length;
 }
 
-function createDebugIdModule() {
-  const code = runtimeDebugIdSnippet(DEBUG_ID_PLACEHOLDER);
+function createDebugIdModule(debugId = DEBUG_ID_PLACEHOLDER) {
+  const code = runtimeDebugIdSnippet(debugId);
   return {
     dependencies: new Map(),
     getSource: () => Buffer.from(code),
@@ -55,14 +58,14 @@ function createDebugIdModule() {
   };
 }
 
-function prependDebugIdModule(preModules) {
+function prependDebugIdModule(preModules, debugId = DEBUG_ID_PLACEHOLDER) {
   if (!Array.isArray(preModules)) {
     throw configurationError("LogBrew Metro serializer expected preModules to be an array");
   }
   if (preModules.some((module) => module?.path === DEBUG_ID_MODULE_PATH)) {
     return preModules;
   }
-  const debugIdModule = createDebugIdModule();
+  const debugIdModule = createDebugIdModule(debugId);
   if (preModules[0]?.path === "__prelude__") {
     return [preModules[0], debugIdModule, ...preModules.slice(1)];
   }
@@ -130,7 +133,12 @@ function sourceWithDebugId(source, debugId) {
 }
 
 function productionResult(result) {
-  if (!result || Array.isArray(result) || typeof result !== "object") {
+  if (Array.isArray(result)) {
+    throw configurationError(
+      "LogBrew Metro received Expo static assets; use getLogBrewExpoConfig instead of withLogBrewMetroConfig for Expo projects",
+    );
+  }
+  if (!result || typeof result !== "object") {
     throw configurationError("LogBrew Metro production serializer must return { code, map }");
   }
   if (typeof result.code !== "string") {
@@ -156,6 +164,81 @@ function productionResult(result) {
   };
 }
 
+function requireExpoPluginOptions(options) {
+  requireOptions(options);
+  if (
+    options.unstable_beforeAssetSerializationPlugins !== undefined &&
+    (!Array.isArray(options.unstable_beforeAssetSerializationPlugins) ||
+      options.unstable_beforeAssetSerializationPlugins.some((plugin) => typeof plugin !== "function"))
+  ) {
+    throw configurationError(
+      "LogBrew Expo option unstable_beforeAssetSerializationPlugins must be an array of functions",
+    );
+  }
+  if (options.getDefaultConfig !== undefined && typeof options.getDefaultConfig !== "function") {
+    throw configurationError("LogBrew Expo option getDefaultConfig must be a function");
+  }
+  return options;
+}
+
+function createLogBrewExpoDebugIdPlugin(options = {}) {
+  requireOptions(options);
+  return (input) => {
+    if (!input || Array.isArray(input) || typeof input !== "object") {
+      throw configurationError("LogBrew Expo Debug ID plugin requires a serialization input object");
+    }
+    const preModules = input.premodules;
+    if (!Array.isArray(preModules)) {
+      throw configurationError("LogBrew Expo Debug ID plugin expected premodules to be an array");
+    }
+    if (options.enabled === false || input.debugId === undefined || input.debugId === null) {
+      return preModules;
+    }
+    if (typeof input.debugId !== "string" || !DEBUG_ID_RE.test(input.debugId)) {
+      throw configurationError("LogBrew Expo Debug ID plugin requires a valid Expo Debug ID");
+    }
+    return prependDebugIdModule(preModules, input.debugId.toLowerCase());
+  };
+}
+
+function loadExpoGetDefaultConfig(projectRoot) {
+  let expoMetroConfig;
+  try {
+    const projectRequire = createRequire(path.join(projectRoot, "package.json"));
+    expoMetroConfig = projectRequire("expo/metro-config");
+  } catch (error) {
+    throw configurationError(
+      "LogBrew could not load expo/metro-config from the app; install a supported Expo SDK or pass getDefaultConfig",
+      { cause: error },
+    );
+  }
+  if (typeof expoMetroConfig?.getDefaultConfig !== "function") {
+    throw configurationError("LogBrew could not resolve getDefaultConfig from expo/metro-config");
+  }
+  return expoMetroConfig.getDefaultConfig;
+}
+
+function getLogBrewExpoConfig(projectRoot, options = {}) {
+  if (typeof projectRoot !== "string" || projectRoot.trim() === "") {
+    throw configurationError("getLogBrewExpoConfig requires a non-empty Expo project root");
+  }
+  requireExpoPluginOptions(options);
+  const root = path.resolve(projectRoot);
+  const {
+    enabled = true,
+    getDefaultConfig = loadExpoGetDefaultConfig(root),
+    unstable_beforeAssetSerializationPlugins = [],
+    ...expoOptions
+  } = options;
+  const plugins = enabled
+    ? [...unstable_beforeAssetSerializationPlugins, createLogBrewExpoDebugIdPlugin()]
+    : [...unstable_beforeAssetSerializationPlugins];
+  return getDefaultConfig(root, {
+    ...expoOptions,
+    unstable_beforeAssetSerializationPlugins: plugins,
+  });
+}
+
 function requireMetroModule(privatePath, sourcePath) {
   try {
     return require(privatePath);
@@ -305,6 +388,7 @@ function withLogBrewMetroConfig(config, options = {}) {
 
 module.exports = {
   createLogBrewMetroSerializer,
+  getLogBrewExpoConfig,
   withLogBrewMetroConfig,
   default: withLogBrewMetroConfig,
 };

package/metro.d.cts

@@ -14,21 +14,41 @@ export type LogBrewMetroSerializer<TModule = unknown, TGraph = unknown, TOptions
 export type LogBrewMetroConfig = {
   serializer?: {
     customSerializer?: unknown;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
-};
+  } | Record<string, unknown>;
+} | Record<string, unknown>;
 
 export type LogBrewMetroConfigOptions = {
   enabled?: boolean;
 };
 
+export type LogBrewExpoSerializationInput<TModule = unknown, TGraph = unknown> = {
+  debugId?: string;
+  graph: TGraph;
+  premodules: TModule[];
+};
+
+export type LogBrewExpoDebugIdPlugin<TModule = unknown, TGraph = unknown> = (
+  input: LogBrewExpoSerializationInput<TModule, TGraph>,
+) => TModule[];
+
+export type LogBrewExpoConfigOptions<TConfig extends LogBrewMetroConfig = LogBrewMetroConfig> = {
+  enabled?: boolean;
+  getDefaultConfig?: (...args: never[]) => TConfig;
+  unstable_beforeAssetSerializationPlugins?: LogBrewExpoDebugIdPlugin[];
+  [key: string]: unknown;
+};
+
 export declare function createLogBrewMetroSerializer<TModule, TGraph, TOptions>(
   customSerializer: LogBrewMetroSerializer<TModule, TGraph, TOptions>,
 ): LogBrewMetroSerializer<TModule, TGraph, TOptions>;
 
 export declare function createLogBrewMetroSerializer(customSerializer?: null): LogBrewMetroSerializer;
 
+export declare function getLogBrewExpoConfig<TConfig extends LogBrewMetroConfig = LogBrewMetroConfig>(
+  projectRoot: string,
+  options?: LogBrewExpoConfigOptions<TConfig>,
+): TConfig;
+
 export declare function withLogBrewMetroConfig<T extends LogBrewMetroConfig>(
   config: T,
   options?: LogBrewMetroConfigOptions,

package/metro.d.ts

@@ -14,21 +14,41 @@ export type LogBrewMetroSerializer<TModule = unknown, TGraph = unknown, TOptions
 export type LogBrewMetroConfig = {
   serializer?: {
     customSerializer?: unknown;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
-};
+  } | Record<string, unknown>;
+} | Record<string, unknown>;
 
 export type LogBrewMetroConfigOptions = {
   enabled?: boolean;
 };
 
+export type LogBrewExpoSerializationInput<TModule = unknown, TGraph = unknown> = {
+  debugId?: string;
+  graph: TGraph;
+  premodules: TModule[];
+};
+
+export type LogBrewExpoDebugIdPlugin<TModule = unknown, TGraph = unknown> = (
+  input: LogBrewExpoSerializationInput<TModule, TGraph>,
+) => TModule[];
+
+export type LogBrewExpoConfigOptions<TConfig extends LogBrewMetroConfig = LogBrewMetroConfig> = {
+  enabled?: boolean;
+  getDefaultConfig?: (...args: never[]) => TConfig;
+  unstable_beforeAssetSerializationPlugins?: LogBrewExpoDebugIdPlugin[];
+  [key: string]: unknown;
+};
+
 export declare function createLogBrewMetroSerializer<TModule, TGraph, TOptions>(
   customSerializer: LogBrewMetroSerializer<TModule, TGraph, TOptions>,
 ): LogBrewMetroSerializer<TModule, TGraph, TOptions>;
 
 export declare function createLogBrewMetroSerializer(customSerializer?: null): LogBrewMetroSerializer;
 
+export declare function getLogBrewExpoConfig<TConfig extends LogBrewMetroConfig = LogBrewMetroConfig>(
+  projectRoot: string,
+  options?: LogBrewExpoConfigOptions<TConfig>,
+): TConfig;
+
 export declare function withLogBrewMetroConfig<T extends LogBrewMetroConfig>(
   config: T,
   options?: LogBrewMetroConfigOptions,

package/metro.js

@@ -1,6 +1,7 @@
 import metro from "./metro.cjs";
 
 export const createLogBrewMetroSerializer = metro.createLogBrewMetroSerializer;
+export const getLogBrewExpoConfig = metro.getLogBrewExpoConfig;
 export const withLogBrewMetroConfig = metro.withLogBrewMetroConfig;
 
 export default withLogBrewMetroConfig;

package/package.json

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