@logbrew/react-native 0.1.7 → 0.1.9

package/README.md

@@ -71,6 +71,11 @@ export async function verifyLogBrewSetup() {
 }
 ```
 
+Screen labels remain available as the original `metadata.screen` value. The
+helper preserves an already machine-safe action name and otherwise normalizes
+and bounds it for hosted ingestion, so labels such as `Checkout Complete` do
+not cause a rejected batch.
+
 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.
@@ -229,7 +234,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
@@ -241,6 +269,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
@@ -255,7 +288,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/index.cjs

@@ -16,6 +16,8 @@ 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 MAX_ACTION_NAME_LENGTH = 64;
+const SCREEN_ACTION_PREFIX = "screen:";
 const BACKGROUND_APP_STATES = new Set(["background", "inactive"]);
 const LogBrewNativeContext = React.createContext(null);
 const activeTraceScopes = [];
@@ -294,7 +296,7 @@ function captureScreenView(client, screenName, {
   requireClient(client);
   requireNonEmpty("screen name", screenName);
   client.action(id, timestamp, {
-    name: `screen:${screenName}`,
+    name: screenActionName(screenName),
     status,
     metadata: {
       ...getReactNativeContext({ platform, appState }),
@@ -1023,6 +1025,22 @@ function slugify(value) {
     .replace(/^_+|_+$/g, "") || "event";
 }
 
+function screenActionName(screenName) {
+  const directName = `${SCREEN_ACTION_PREFIX}${screenName}`;
+  if (
+    directName.length <= MAX_ACTION_NAME_LENGTH
+    && /^[a-z0-9_.:-]+$/i.test(directName)
+  ) {
+    return directName;
+  }
+
+  const maxScreenSegmentLength = MAX_ACTION_NAME_LENGTH - SCREEN_ACTION_PREFIX.length;
+  const screenSegment = slugify(screenName)
+    .slice(0, maxScreenSegmentLength)
+    .replace(/_+$/g, "") || "event";
+  return `${SCREEN_ACTION_PREFIX}${screenSegment}`;
+}
+
 function statusFromStatusCode(statusCode) {
   if (typeof statusCode === "number" && Number.isFinite(statusCode) && statusCode >= 400) {
     return "failure";

package/index.js

@@ -16,6 +16,8 @@ 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 MAX_ACTION_NAME_LENGTH = 64;
+const SCREEN_ACTION_PREFIX = "screen:";
 const BACKGROUND_APP_STATES = new Set(["background", "inactive"]);
 const LogBrewNativeContext = React.createContext(null);
 const activeTraceScopes = [];
@@ -294,7 +296,7 @@ export function captureScreenView(client, screenName, {
   requireClient(client);
   requireNonEmpty("screen name", screenName);
   client.action(id, timestamp, {
-    name: `screen:${screenName}`,
+    name: screenActionName(screenName),
     status,
     metadata: {
       ...getReactNativeContext({ platform, appState }),
@@ -1012,6 +1014,22 @@ function slugify(value) {
     .replace(/^_+|_+$/g, "") || "event";
 }
 
+function screenActionName(screenName) {
+  const directName = `${SCREEN_ACTION_PREFIX}${screenName}`;
+  if (
+    directName.length <= MAX_ACTION_NAME_LENGTH
+    && /^[a-z0-9_.:-]+$/i.test(directName)
+  ) {
+    return directName;
+  }
+
+  const maxScreenSegmentLength = MAX_ACTION_NAME_LENGTH - SCREEN_ACTION_PREFIX.length;
+  const screenSegment = slugify(screenName)
+    .slice(0, maxScreenSegmentLength)
+    .replace(/_+$/g, "") || "event";
+  return `${SCREEN_ACTION_PREFIX}${screenSegment}`;
+}
+
 function statusFromStatusCode(statusCode) {
   if (typeof statusCode === "number" && Number.isFinite(statusCode) && statusCode >= 400) {
     return "failure";

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.7",
+  "version": "0.1.9",
   "description": "React Native screen, error, trace, action, and network timeline helpers for LogBrew.",
   "type": "module",
   "main": "./index.cjs",