@logbrew/react-native 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# @logbrew/react-native
+
+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, handled JavaScript errors, provider/hook usage, and explicit W3C trace propagation for mobile fetch calls.
+
+## Install
+
+```bash
+npm install @logbrew/sdk @logbrew/react-native react react-native
+pnpm add @logbrew/sdk @logbrew/react-native react react-native
+```
+
+## Basic Usage
+
+```js
+import { AppState, Platform } from "react-native";
+import {
+  captureScreenView,
+  createAppStateListener,
+  createLogBrewReactNativeClient
+} from "@logbrew/react-native";
+
+const client = createLogBrewReactNativeClient({
+  clientKey: "LOGBREW_CLIENT_KEY",
+  sdkName: "my-mobile-app",
+  sdkVersion: "0.1.0"
+});
+
+captureScreenView(client, "Checkout", {
+  platform: Platform,
+  appState: AppState,
+  timestamp: "2026-06-02T10:00:03Z"
+});
+
+const stopListening = createAppStateListener(client, AppState, {
+  platform: Platform
+});
+```
+
+For mobile apps, prefer an app-scoped public key through `clientKey`. `apiKey` is still accepted for compatibility with lower-level SDK examples and tests.
+
+## Error Capture
+
+Use `captureReactNativeError()` in app-owned error boundaries, route handlers, async catch blocks, or global handlers. It records handled JavaScript errors as LogBrew issue events with React Native context and omits stack text by default:
+
+```js
+import { captureReactNativeError } from "@logbrew/react-native";
+
+try {
+  await checkout();
+} catch (error) {
+  captureReactNativeError(client, error, {
+    platform: Platform,
+    appState: AppState,
+    screen: "Checkout",
+    metadata: { flow: "checkout" }
+  });
+  throw error;
+}
+```
+
+Set `includeStack: true` only when your app has decided stack text is safe to send. Non-`Error` thrown values are accepted and converted into issue messages so app error handlers do not need custom guards.
+
+## Provider And Hooks
+
+```js
+import { AppState, Platform } from "react-native";
+import {
+  LogBrewNativeProvider,
+  useLogBrewNativeActions
+} from "@logbrew/react-native";
+
+function CheckoutScreen() {
+  const { captureScreenView } = useLogBrewNativeActions();
+  captureScreenView("Checkout");
+  return null;
+}
+
+export function App({ client }) {
+  return (
+    <LogBrewNativeProvider client={client} platform={Platform} appState={AppState}>
+      <CheckoutScreen />
+    </LogBrewNativeProvider>
+  );
+}
+```
+
+The package ships a `react-native` entry that imports `AppState` and `Platform` for Metro, while the default Node entry accepts those dependencies explicitly. That keeps packaged examples and CI smoke tests runnable without pretending a Node process is a native runtime.
+
+## Trace Propagation
+
+Use `createTraceparentFetch()` when a React Native app should connect mobile fetch work to backend traces. Propagation is target-scoped by default: no `traceparent` header is attached unless the request URL matches `tracePropagationTargets`.
+
+```js
+import {
+  createReactNativeTraceparent,
+  createTraceparentFetch
+} from "@logbrew/react-native";
+
+const tracedFetch = createTraceparentFetch({
+  traceparentFactory: () => createReactNativeTraceparent(),
+  tracePropagationTargets: [
+    "https://api.example.com/",
+    /^\/mobile-api\//
+  ]
+});
+
+await tracedFetch("https://api.example.com/checkout", {
+  method: "POST",
+  headers: { accept: "application/json" }
+});
+```
+
+`tracePropagationTargets` accepts strings, regular expressions, or `(url) => boolean` functions. Match narrowly so mobile requests do not send tracing headers to unrelated origins. If the API is cross-origin or behind a gateway, allow the `traceparent` request header there too.
+
+## Packaged Examples
+
+After install, these commands are available from a consumer app:
+
+```bash
+node node_modules/@logbrew/react-native/examples/index.mjs --help
+node node_modules/@logbrew/react-native/examples/index.mjs --list
+node node_modules/@logbrew/react-native/examples/index.mjs readme-example
+node node_modules/@logbrew/react-native/examples/index.mjs real-user-smoke
+node node_modules/@logbrew/react-native/examples/index.mjs
+npm --prefix node_modules/@logbrew/react-native/examples run help
+npm --prefix node_modules/@logbrew/react-native/examples run list
+npm --prefix node_modules/@logbrew/react-native/examples run readme-example
+npm --prefix node_modules/@logbrew/react-native/examples run real-user-smoke
+```
+
+The default launcher path runs `real-user-smoke`.

package/examples/index.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+const commands = new Map([
+  ["readme-example", new URL("./readme-example.mjs", import.meta.url)],
+  ["real-user-smoke", new URL("./real-user-smoke.mjs", import.meta.url)]
+]);
+
+const command = process.argv[2] ?? "real-user-smoke";
+
+if (command === "--help" || command === "-h") {
+  printHelp();
+} else if (command === "--list") {
+  printList();
+} else if (commands.has(command)) {
+  await import(commands.get(command));
+} else {
+  console.error(`Unknown LogBrew React Native example: ${command}`);
+  printList();
+  process.exitCode = 1;
+}
+
+function printHelp() {
+  console.log("LogBrew React Native examples");
+  console.log("node node_modules/@logbrew/react-native/examples/index.mjs --list");
+  console.log("node node_modules/@logbrew/react-native/examples/index.mjs readme-example");
+  console.log("node node_modules/@logbrew/react-native/examples/index.mjs real-user-smoke");
+  console.log("node node_modules/@logbrew/react-native/examples/index.mjs");
+  console.log("npm --prefix node_modules/@logbrew/react-native/examples run list");
+  console.log("npm --prefix node_modules/@logbrew/react-native/examples run readme-example");
+  console.log("npm --prefix node_modules/@logbrew/react-native/examples run real-user-smoke");
+}
+
+function printList() {
+  console.log("readme-example -> node node_modules/@logbrew/react-native/examples/index.mjs readme-example");
+  console.log("real-user-smoke -> node node_modules/@logbrew/react-native/examples/index.mjs real-user-smoke");
+}

package/examples/package.json

@@ -0,0 +1,10 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "help": "node ./index.mjs --help",
+    "list": "node ./index.mjs --list",
+    "readme-example": "node ./index.mjs readme-example",
+    "real-user-smoke": "node ./index.mjs real-user-smoke"
+  }
+}

package/examples/readme-example.mjs

@@ -0,0 +1,60 @@
+import { RecordingTransport } from "@logbrew/sdk";
+import {
+  captureScreenView,
+  createLogBrewReactNativeClient
+} from "@logbrew/react-native";
+
+const fakePlatform = {
+  OS: "ios",
+  Version: "18.0",
+  isPad: false,
+  constants: { isTesting: true }
+};
+const fakeAppState = { currentState: "active" };
+const client = createLogBrewReactNativeClient({
+  clientKey: "LOGBREW_CLIENT_KEY",
+  sdkName: "logbrew-react-native-readme-example",
+  sdkVersion: "0.1.0"
+});
+
+addFullBatch(client);
+captureScreenView(client, "Checkout", {
+  id: "evt_action_001",
+  timestamp: "2026-06-02T10:00:05Z",
+  platform: fakePlatform,
+  appState: fakeAppState,
+  metadata: { flow: "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 }));
+
+function addFullBatch(client) {
+  client.release("evt_release_001", "2026-06-02T10:00:00Z", {
+    version: "1.2.3",
+    commit: "abc123def456",
+    notes: "Public release marker"
+  });
+  client.environment("evt_environment_001", "2026-06-02T10:00:01Z", {
+    name: "production",
+    region: "global"
+  });
+  client.issue("evt_issue_001", "2026-06-02T10:00:02Z", {
+    title: "Checkout timeout",
+    level: "error",
+    message: "Request timed out after retry budget"
+  });
+  client.log("evt_log_001", "2026-06-02T10:00:03Z", {
+    message: "worker started",
+    level: "info",
+    logger: "job-runner"
+  });
+  client.span("evt_span_001", "2026-06-02T10:00:04Z", {
+    name: "GET /health",
+    traceId: "trace_001",
+    spanId: "span_001",
+    status: "ok",
+    durationMs: 12.5
+  });
+}

package/examples/real-user-smoke.mjs

@@ -0,0 +1,145 @@
+import { RecordingTransport } from "@logbrew/sdk";
+import {
+  captureReactNativeError,
+  captureScreenView,
+  createAppStateListener,
+  createLogBrewReactNativeClient,
+  createReactNativeTraceparent,
+  createTraceparentFetch,
+  shouldPropagateTraceparent
+} from "@logbrew/react-native";
+
+const fakePlatform = {
+  OS: "android",
+  Version: 35,
+  isPad: false,
+  constants: { isTesting: true }
+};
+let appStateListener = null;
+const fakeAppState = {
+  currentState: "active",
+  addEventListener(_type, listener) {
+    appStateListener = listener;
+    return {
+      remove() {
+        appStateListener = null;
+      }
+    };
+  }
+};
+
+const client = createLogBrewReactNativeClient({
+  clientKey: "LOGBREW_CLIENT_KEY",
+  sdkName: "logbrew-react-native-real-user-smoke",
+  sdkVersion: "0.1.0",
+  maxRetries: 1
+});
+
+addCoreEvents(client);
+captureScreenView(client, "Checkout", {
+  id: "evt_action_001",
+  timestamp: "2026-06-02T10:00:05Z",
+  platform: fakePlatform,
+  appState: fakeAppState,
+  metadata: { flow: "checkout" }
+});
+const stopListening = createAppStateListener(client, fakeAppState, {
+  id: "evt_action_app_state_background",
+  timestamp: "2026-06-02T10:00:06Z",
+  platform: fakePlatform
+});
+appStateListener("background");
+stopListening();
+const handledError = new Error("Checkout failed on device");
+captureReactNativeError(client, handledError, {
+  id: "evt_issue_react_native_error",
+  timestamp: "2026-06-02T10:00:07Z",
+  platform: fakePlatform,
+  appState: fakeAppState,
+  screen: "Checkout",
+  metadata: { flow: "checkout", handled: true }
+});
+
+const propagatedRequests = [];
+const tracedFetch = createTraceparentFetch({
+  fetchImpl: async (input, init = {}) => {
+    propagatedRequests.push({ input, init });
+    return { status: 204 };
+  },
+  traceparentFactory: () => createReactNativeTraceparent({
+    randomValues: deterministicBytes
+  }),
+  tracePropagationTargets: ["https://api.example.test/", /^\/mobile-api\//u]
+});
+if (!shouldPropagateTraceparent("https://api.example.test/checkout", ["https://api.example.test/"])) {
+  throw new Error("expected API request to match trace propagation target");
+}
+if (shouldPropagateTraceparent("https://cdn.example.test/app.js", ["https://api.example.test/"])) {
+  throw new Error("expected CDN request not to match trace propagation target");
+}
+await tracedFetch("https://api.example.test/checkout", {
+  headers: { accept: "application/json", traceparent: "00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01" }
+});
+await tracedFetch("https://cdn.example.test/app.js", {
+  headers: { accept: "text/javascript" }
+});
+await tracedFetch("/mobile-api/cart");
+const propagatedTraceparent = propagatedRequests[0].init.headers.traceparent;
+if (propagatedTraceparent !== "00-0102030405060708090a0b0c0d0e0f10-0102030405060708-01") {
+  throw new Error(`unexpected propagated traceparent: ${propagatedTraceparent}`);
+}
+if (propagatedRequests[0].init.headers.accept !== "application/json") {
+  throw new Error("expected traced fetch to preserve existing headers");
+}
+if (propagatedRequests[1].init.headers?.traceparent !== undefined) {
+  throw new Error("unmatched requests should not receive traceparent");
+}
+if (propagatedRequests[2].init.headers.traceparent !== propagatedTraceparent) {
+  throw new Error("relative matched requests should receive traceparent");
+}
+
+const preview = client.previewJson();
+const transport = new RecordingTransport([{ statusCode: 503 }, { statusCode: 202 }]);
+const response = await client.shutdown(transport);
+console.log(preview);
+console.error(JSON.stringify({
+  ok: true,
+  status: response.statusCode,
+  attempts: response.attempts,
+  events: 8,
+  listenerRemoved: appStateListener === null,
+  propagatedTraceparent
+}));
+
+function addCoreEvents(client) {
+  client.release("evt_release_001", "2026-06-02T10:00:00Z", {
+    version: "1.2.3",
+    commit: "abc123def456",
+    notes: "Public release marker"
+  });
+  client.environment("evt_environment_001", "2026-06-02T10:00:01Z", {
+    name: "production",
+    region: "global"
+  });
+  client.issue("evt_issue_001", "2026-06-02T10:00:02Z", {
+    title: "Checkout timeout",
+    level: "error",
+    message: "Request timed out after retry budget"
+  });
+  client.log("evt_log_001", "2026-06-02T10:00:03Z", {
+    message: "worker started",
+    level: "info",
+    logger: "job-runner"
+  });
+  client.span("evt_span_001", "2026-06-02T10:00:04Z", {
+    name: "GET /health",
+    traceId: "trace_001",
+    spanId: "span_001",
+    status: "ok",
+    durationMs: 12.5
+  });
+}
+
+function deterministicBytes(length) {
+  return Uint8Array.from({ length }, (_value, index) => index + 1);
+}