@logbrew/react-native 0.1.19 → 0.1.21

package/README.md

@@ -309,7 +309,8 @@ before root registration, then start replay:
 ```js
 import {
   installLogBrewAppleNativeDiagnostics,
-  replayLogBrewAppleNativeDiagnostics
+  replayLogBrewAppleNativeDiagnostics,
+  setLogBrewAppleNativeCrashContext
 } from "@logbrew/react-native/apple-native-diagnostics";
 
 const nativeStatus = installLogBrewAppleNativeDiagnostics({
@@ -322,6 +323,13 @@ const nativeStatus = installLogBrewAppleNativeDiagnostics({
   hangThresholdSeconds: 2
 });
 
+setLogBrewAppleNativeCrashContext({
+  schemaVersion: 1,
+  trace: { traceId: trace.traceId, spanId: trace.spanId, sampled: trace.sampled },
+  session: { id: "session_123" },
+  subject: { id: "subject_456", kind: "user" }
+});
+
 void replayLogBrewAppleNativeDiagnostics().catch((error) => {
   console.warn(error?.code ?? "native_diagnostics_failed");
 });
@@ -334,6 +342,21 @@ 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
+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.
+
+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
 the configured project does not replay an earlier project's records with the

package/apple-native-diagnostics.d.ts

@@ -1,3 +1,5 @@
+import type { TelemetrySessionContext, TelemetrySubjectContext, TelemetryTraceContext } from "@logbrew/sdk";
+
 type LogBrewAppleNativeDiagnosticsAuth =
   | { apiKey: string; clientKey?: never }
   | { clientKey: string; apiKey?: never };
@@ -32,6 +34,19 @@ export type LogBrewAppleNativeDiagnosticsReplayResult = Readonly<{
   pending: number;
 }>;
 
+export type LogBrewAppleNativeCrashContext = {
+  schemaVersion: 1;
+  trace?: TelemetryTraceContext;
+  session?: TelemetrySessionContext;
+  subject?: TelemetrySubjectContext;
+  resource?: never;
+  tags?: never;
+};
+
+export type LogBrewAppleNativeCrashContextResult = Readonly<{
+  status: "cleared" | "updated";
+}>;
+
 export declare function installLogBrewAppleNativeDiagnostics(
   configuration: LogBrewAppleNativeDiagnosticsConfiguration
 ): LogBrewAppleNativeDiagnosticsStatus;
@@ -43,10 +58,15 @@ export declare function replayLogBrewAppleNativeDiagnostics(): Promise<
 export declare function getLogBrewAppleNativeDiagnosticsStatus():
   LogBrewAppleNativeDiagnosticsStatus;
 
+export declare function setLogBrewAppleNativeCrashContext(
+  context: LogBrewAppleNativeCrashContext | null
+): LogBrewAppleNativeCrashContextResult;
+
 declare const defaultExport: {
   getLogBrewAppleNativeDiagnosticsStatus: typeof getLogBrewAppleNativeDiagnosticsStatus;
   installLogBrewAppleNativeDiagnostics: typeof installLogBrewAppleNativeDiagnostics;
   replayLogBrewAppleNativeDiagnostics: typeof replayLogBrewAppleNativeDiagnostics;
+  setLogBrewAppleNativeCrashContext: typeof setLogBrewAppleNativeCrashContext;
 };
 
 export default defaultExport;

package/apple-native-diagnostics.js

@@ -44,6 +44,40 @@ export function getLogBrewAppleNativeDiagnosticsStatus() {
   return requireStatusResult("status", result, new Set(["not_installed", "ready"]));
 }
 
+export function setLogBrewAppleNativeCrashContext(context) {
+  requireApplePlatform();
+  const nativeModule = requireNativeModule();
+  const payload = context === null ? null : normalizeCorrelationContext(context);
+  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 ${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 ${label} returned an invalid response`
+    );
+  }
+  return Object.freeze({ status: expectedStatus });
+}
+
 function normalizeConfiguration(configuration) {
   if (!configuration
     || Array.isArray(configuration)
@@ -109,6 +143,81 @@ function normalizeConfiguration(configuration) {
   return payload;
 }
 
+function normalizeCorrelationContext(context) {
+  const source = exactObject(context, ["schemaVersion", "session", "subject", "trace"], "context");
+  if (source.schemaVersion !== 1) {
+    throw configurationError("context schemaVersion must be 1");
+  }
+  const output = { schemaVersion: 1 };
+  if (source.trace !== undefined) {
+    const trace = exactObject(
+      source.trace,
+      ["parentSpanId", "sampled", "spanId", "traceId"],
+      "context trace"
+    );
+    output.trace = { traceId: correlationHexId(trace.traceId, 32, "traceId") };
+    for (const [key, width] of [["spanId", 16], ["parentSpanId", 16]]) {
+      if (trace[key] !== undefined) {
+        output.trace[key] = correlationHexId(trace[key], width, key);
+      }
+    }
+    if (trace.sampled !== undefined) {
+      if (typeof trace.sampled !== "boolean") {
+        throw configurationError("context trace sampled must be a boolean");
+      }
+      output.trace.sampled = trace.sampled;
+    }
+  }
+  if (source.session !== undefined) {
+    const session = exactObject(source.session, ["id", "previousId"], "context session");
+    output.session = { id: opaqueCorrelationId(session.id, "session id") };
+    if (session.previousId !== undefined) {
+      output.session.previousId = opaqueCorrelationId(session.previousId, "session previousId");
+      if (output.session.previousId === output.session.id) {
+        throw configurationError("context session previousId must differ from id");
+      }
+    }
+  }
+  if (source.subject !== undefined) {
+    const subject = exactObject(source.subject, ["id", "kind"], "context subject");
+    if (subject.kind !== "anonymous" && subject.kind !== "user") {
+      throw configurationError("context subject kind must be anonymous or user");
+    }
+    output.subject = { id: opaqueCorrelationId(subject.id, "subject id"), kind: subject.kind };
+  }
+  if (Object.keys(output).length === 1) {
+    throw configurationError("context must include trace, session, or subject");
+  }
+  return output;
+}
+
+function exactObject(value, allowedKeys, name) {
+  if (!isPlainObject(value)) {
+    throw configurationError(`${name} must be an object`);
+  }
+  const unknown = Object.keys(value).filter((key) => !allowedKeys.includes(key)).sort();
+  if (unknown.length > 0) {
+    throw configurationError(`${name} contains unsupported fields`);
+  }
+  return value;
+}
+
+function correlationHexId(value, width, name) {
+  if (typeof value !== "string"
+    || !new RegExp(`^[0-9a-f]{${width}}$`, "iu").test(value)
+    || /^0+$/u.test(value)) {
+    throw configurationError(`context trace ${name} must be a non-zero ${width}-character hex value`);
+  }
+  return value.toLowerCase();
+}
+
+function opaqueCorrelationId(value, name) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/u.test(value)) {
+    throw configurationError(`context ${name} must be an opaque app-owned identifier`);
+  }
+  return value;
+}
+
 function requireApplePlatform() {
   if (Platform?.OS !== "ios") {
     throw new SdkError(
@@ -280,7 +389,8 @@ function configurationError(message) {
 const logBrewAppleNativeDiagnostics = {
   getLogBrewAppleNativeDiagnosticsStatus,
   installLogBrewAppleNativeDiagnostics,
-  replayLogBrewAppleNativeDiagnostics
+  replayLogBrewAppleNativeDiagnostics,
+  setLogBrewAppleNativeCrashContext
 };
 
 export default logBrewAppleNativeDiagnostics;

package/index.cjs

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