@logbrew/react-native 0.1.20 → 0.1.22

package/README.md

@@ -327,7 +327,11 @@ setLogBrewAppleNativeCrashContext({
   schemaVersion: 1,
   trace: { traceId: trace.traceId, spanId: trace.spanId, sampled: trace.sampled },
   session: { id: "session_123" },
-  subject: { id: "subject_456", kind: "user" }
+  subject: { id: "subject_456", kind: "user" },
+  impact: {
+    failedAction: "checkout.submit",
+    userVisibleOutcome: "The order was not confirmed."
+  }
 });
 
 void replayLogBrewAppleNativeDiagnostics().catch((error) => {
@@ -342,10 +346,25 @@ allowed, but only one integration may install native fatal capture in a given
 process. LogBrew cannot transfer or remove that ownership before process
 restart.
 
-Update this snapshot when the active trace, session, or subject changes, and
+Update this snapshot when the active trace, session, subject, or failed action changes, and
 clear it with `setLogBrewAppleNativeCrashContext(null)` on logout or session
 end. The crash report keeps one atomic snapshot from the crashed process, so a
-later app launch cannot replace it. Session and subject values must be opaque app-owned identifiers made from ASCII letters, numbers, `_`, or `-`. Do not use names, email addresses, IP addresses, or device identifiers. Resource context, tags, arbitrary fields, and values over the fixed 1 KiB snapshot limit fail before storage.
+later app launch cannot replace it. `impact` is explicit app knowledge. Use a
+stable action name and an optional safe user-visible result. Never include raw
+input, request data, authentication values, or identity. Session and subject values must
+be opaque app-owned identifiers made from ASCII letters, numbers, `_`, or `-`.
+Resource context, tags, arbitrary fields, and values over the fixed 4 KiB
+snapshot limit fail before storage.
+
+The iOS `createLogBrewReactNativeClient()` entry also mirrors its validated
+breadcrumb history into native crash capture. Install Apple diagnostics first,
+then use the normal screen, app-state, action, network, or `addBreadcrumb()`
+helpers. A fatal crash retains the newest complete entries in oldest-to-newest
+order. The snapshot keeps at most 64 entries and 64 KiB, drops oldest entries
+when either limit is reached, and reports truncation. `clearBreadcrumbs()`
+clears both the JavaScript history and its native crash snapshot. Missing,
+corrupt, and captured breadcrumb state remains explicit on replay; corrupt
+optional context never discards the crash.
 
 Installation creates app-private, data-protected storage that iOS excludes from
 device data archives. Pending reports are partitioned by project, so changing

package/apple-native-diagnostics.d.ts

@@ -36,6 +36,11 @@ export type LogBrewAppleNativeDiagnosticsReplayResult = Readonly<{
 
 export type LogBrewAppleNativeCrashContext = {
   schemaVersion: 1;
+  /** App-reported failed action and optional user-visible result. Never include raw input or identity. */
+  impact?: {
+    failedAction: string;
+    userVisibleOutcome?: string;
+  };
   trace?: TelemetryTraceContext;
   session?: TelemetrySessionContext;
   subject?: TelemetrySubjectContext;

package/apple-native-diagnostics.js

@@ -48,17 +48,31 @@ export function setLogBrewAppleNativeCrashContext(context) {
   requireApplePlatform();
   const nativeModule = requireNativeModule();
   const payload = context === null ? null : normalizeCorrelationContext(context);
-  const result = callNative(nativeModule, "setNativeDiagnosticsContext", payload);
+  return updateNativeSnapshot(nativeModule, "setNativeDiagnosticsContext", payload, "context");
+}
+
+export function syncLogBrewAppleNativeCrashBreadcrumbs(snapshot) {
+  requireApplePlatform();
+  return updateNativeSnapshot(
+    requireNativeModule(),
+    "setNativeDiagnosticsBreadcrumbs",
+    snapshot,
+    "breadcrumbs"
+  );
+}
+
+function updateNativeSnapshot(nativeModule, method, payload, label) {
+  const result = callNative(nativeModule, method, payload);
   const expectedStatus = payload === null ? "cleared" : "updated";
   if (isErrorResult(result)) {
-    throw new SdkError(result.code, `LogBrew Apple native diagnostics context failed with ${result.code}`);
+    throw new SdkError(result.code, `LogBrew Apple native diagnostics ${label} failed with ${result.code}`);
   }
   if (!isPlainObject(result)
     || Object.keys(result).length !== 1
     || result.status !== expectedStatus) {
     throw new SdkError(
       "native_diagnostics_invalid_response",
-      "LogBrew Apple native diagnostics context returned an invalid response"
+      `LogBrew Apple native diagnostics ${label} returned an invalid response`
     );
   }
   return Object.freeze({ status: expectedStatus });
@@ -130,7 +144,11 @@ function normalizeConfiguration(configuration) {
 }
 
 function normalizeCorrelationContext(context) {
-  const source = exactObject(context, ["schemaVersion", "session", "subject", "trace"], "context");
+  const source = exactObject(
+    context,
+    ["impact", "schemaVersion", "session", "subject", "trace"],
+    "context"
+  );
   if (source.schemaVersion !== 1) {
     throw configurationError("context schemaVersion must be 1");
   }
@@ -171,8 +189,26 @@ function normalizeCorrelationContext(context) {
     }
     output.subject = { id: opaqueCorrelationId(subject.id, "subject id"), kind: subject.kind };
   }
+  if (source.impact !== undefined) {
+    const impact = exactObject(
+      source.impact,
+      ["failedAction", "userVisibleOutcome"],
+      "context impact"
+    );
+    output.impact = {
+      failedAction: diagnosticText(impact.failedAction, 256, true, "failedAction")
+    };
+    if (impact.userVisibleOutcome !== undefined) {
+      output.impact.userVisibleOutcome = diagnosticText(
+        impact.userVisibleOutcome,
+        512,
+        false,
+        "userVisibleOutcome"
+      );
+    }
+  }
   if (Object.keys(output).length === 1) {
-    throw configurationError("context must include trace, session, or subject");
+    throw configurationError("context must include trace, session, subject, or impact");
   }
   return output;
 }
@@ -204,6 +240,17 @@ function opaqueCorrelationId(value, name) {
   return value;
 }
 
+function diagnosticText(value, maximum, rejectLocationText, name) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (normalized.length === 0
+    || Array.from(normalized).length > maximum
+    || hasControlCharacter(normalized)
+    || (rejectLocationText && /[?#]/u.test(normalized))) {
+    throw configurationError(`context impact ${name} is invalid`);
+  }
+  return normalized;
+}
+
 function requireApplePlatform() {
   if (Platform?.OS !== "ios") {
     throw new SdkError(
@@ -352,7 +399,7 @@ function exactDeliveryEndpoint(value) {
 function hasControlCharacter(value) {
   for (const scalar of value) {
     const codePoint = scalar.codePointAt(0);
-    if (codePoint <= 0x1f || codePoint === 0x7f) {
+    if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
       return true;
     }
   }

package/index.cjs

@@ -16,7 +16,7 @@ const {
 } = require("./metadata.cjs");
 
 const DEFAULT_SDK_NAME = "logbrew-react-native";
-const DEFAULT_SDK_VERSION = "0.1.20";
+const DEFAULT_SDK_VERSION = "0.1.22";
 const DEFAULT_ENDPOINT = "https://api.logbrew.co/v1/events";
 const MAX_ACTION_NAME_LENGTH = 64;
 const MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH = 256;

package/index.native.js

@@ -14,7 +14,8 @@ import {
   getLogBrewAppleNativeDiagnosticsStatus,
   installLogBrewAppleNativeDiagnostics,
   replayLogBrewAppleNativeDiagnostics,
-  setLogBrewAppleNativeCrashContext
+  setLogBrewAppleNativeCrashContext,
+  syncLogBrewAppleNativeCrashBreadcrumbs
 } from "./apple-native-diagnostics.js";
 import {
   purgeReactNativePersistentQueue,
@@ -50,7 +51,7 @@ export function createLogBrewReactNativeClient(config = {}) {
   ) && input.persistentQueue !== undefined;
   const authKey = clientKey ?? apiKey;
   if (typeof authKey !== "string" || authKey.trim() === "") {
-    return createPlatformNeutralClient(input);
+    return bindAppleNativeCrashBreadcrumbs(createPlatformNeutralClient(input));
   }
   const resolved = resolveReactNativePersistentEventStore({
     authKey,
@@ -61,20 +62,72 @@ export function createLogBrewReactNativeClient(config = {}) {
     hasExplicitPersistentQueue
   });
   try {
-    return createPlatformNeutralClient({
+    return bindAppleNativeCrashBreadcrumbs(createPlatformNeutralClient({
       ...forwarded,
       apiKey,
       clientKey,
       eventStore: resolved.eventStore,
       maxQueueBytes,
       maxQueueSize
-    });
+    }));
   } catch (error) {
     resolved.abort();
     throw error;
   }
 }
 
+function bindAppleNativeCrashBreadcrumbs(client) {
+  if (Platform?.OS !== "ios") {
+    return client;
+  }
+  const addBreadcrumb = client.addBreadcrumb.bind(client);
+  const clearBreadcrumbs = client.clearBreadcrumbs.bind(client);
+  client.addBreadcrumb = (...args) => updateAppleNativeBreadcrumbs(
+    client, () => addBreadcrumb(...args)
+  );
+  client.clearBreadcrumbs = () => updateAppleNativeBreadcrumbs(client, clearBreadcrumbs);
+  syncAppleNativeCrashBreadcrumbs(client);
+  return client;
+}
+
+function updateAppleNativeBreadcrumbs(client, update) {
+  const previous = [client.issueBreadcrumbs.slice(), client.issueBreadcrumbsTruncated];
+  const result = update();
+  try {
+    syncAppleNativeCrashBreadcrumbs(client);
+  } catch (error) {
+    restoreBreadcrumbs(client, previous);
+    throw error;
+  }
+  return result;
+}
+
+function restoreBreadcrumbs(client, [breadcrumbs, truncated]) {
+  client.issueBreadcrumbs.splice(0, client.issueBreadcrumbs.length, ...breadcrumbs);
+  client.issueBreadcrumbsTruncated = truncated;
+}
+
+function syncAppleNativeCrashBreadcrumbs(client) {
+  const snapshot = client.issueBreadcrumbs.length === 0
+    ? null
+    : {
+        breadcrumbs: client.issueBreadcrumbs.map(({ data, ...breadcrumb }) => ({
+          ...breadcrumb,
+          ...(data === undefined ? {} : { data: { ...data } })
+        })),
+        schemaVersion: 1,
+        truncated: client.issueBreadcrumbsTruncated
+      };
+  try {
+    syncLogBrewAppleNativeCrashBreadcrumbs(snapshot);
+  } catch (error) {
+    if (error?.code !== "native_diagnostics_unavailable"
+      && error?.code !== "native_diagnostics_not_installed") {
+      throw error;
+    }
+  }
+}
+
 export function purgeLogBrewReactNativePersistentQueue(config = {}) {
   purgeReactNativePersistentQueue(config);
 }