@logbrew/react-native 0.1.6 → 0.1.7

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
 

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/package.json

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