@debugbundle/sdk-react-native 0.1.0

package/src/console.ts

@@ -0,0 +1,38 @@
+import type { DebugBundleClient, DebugBundleLogLevel } from "./types.js";
+
+let restoreConsole: (() => void) | null = null;
+
+export function captureDebugBundleConsole(client: Pick<DebugBundleClient, "captureLog">): () => void {
+  if (restoreConsole) {
+    return restoreConsole;
+  }
+  const originalWarn = console.warn;
+  const originalError = console.error;
+  let inCapture = false;
+  console.warn = (...args: unknown[]) => {
+    capture("warning", args);
+    originalWarn(...args);
+  };
+  console.error = (...args: unknown[]) => {
+    capture("error", args);
+    originalError(...args);
+  };
+  restoreConsole = () => {
+    console.warn = originalWarn;
+    console.error = originalError;
+    restoreConsole = null;
+  };
+  return restoreConsole;
+
+  function capture(level: DebugBundleLogLevel, args: unknown[]): void {
+    if (inCapture) {
+      return;
+    }
+    inCapture = true;
+    try {
+      client.captureLog(args.map(String).join(" "), level, { source: "console" });
+    } finally {
+      inCapture = false;
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,64 @@
+import type { DebugBundleClient } from "./types.js";
+
+export interface ErrorHandlerInstallOptions {
+  captureUnhandledRejections?: boolean;
+}
+
+let restoreHandlers: (() => void) | null = null;
+
+export function installDebugBundleErrorHandlers(
+  client: Pick<DebugBundleClient, "captureException">,
+  options: ErrorHandlerInstallOptions = {}
+): () => void {
+  if (restoreHandlers) {
+    return restoreHandlers;
+  }
+  const restores: Array<() => void> = [];
+  const errorUtils = (globalThis as { ErrorUtils?: ReactNativeErrorUtils }).ErrorUtils;
+
+  if (errorUtils?.setGlobalHandler) {
+    const previousHandler = errorUtils.getGlobalHandler?.();
+    errorUtils.setGlobalHandler((error, isFatal) => {
+      client.captureException(error, {
+        source: "react-native-global-error",
+        fatal: Boolean(isFatal)
+      });
+      previousHandler?.(error, isFatal);
+    });
+    restores.push(() => {
+      if (previousHandler) {
+        errorUtils.setGlobalHandler?.(previousHandler);
+      }
+    });
+  }
+
+  if (options.captureUnhandledRejections !== false && hasAddEventListener(globalThis)) {
+    const listener = (event: PromiseRejectionEvent) => {
+      client.captureException(event.reason ?? new Error("Unhandled promise rejection"), {
+        source: "unhandledrejection"
+      });
+    };
+    globalThis.addEventListener("unhandledrejection", listener);
+    restores.push(() => globalThis.removeEventListener("unhandledrejection", listener));
+  }
+
+  restoreHandlers = () => {
+    for (const restore of restores.reverse()) {
+      restore();
+    }
+    restoreHandlers = null;
+  };
+  return restoreHandlers;
+}
+
+interface ReactNativeErrorUtils {
+  getGlobalHandler?: () => ((error: unknown, isFatal?: boolean) => void) | undefined;
+  setGlobalHandler?: (handler: (error: unknown, isFatal?: boolean) => void) => void;
+}
+
+function hasAddEventListener(value: typeof globalThis): value is typeof globalThis & {
+  addEventListener: (type: "unhandledrejection", listener: (event: PromiseRejectionEvent) => void) => void;
+  removeEventListener: (type: "unhandledrejection", listener: (event: PromiseRejectionEvent) => void) => void;
+} {
+  return "addEventListener" in value && "removeEventListener" in value;
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { DebugBundleReactNativeClient, createDebugBundleClient } from "./client.js";
+import { captureDebugBundleConsole } from "./console.js";
+import { installDebugBundleErrorHandlers } from "./errors.js";
+import type {
+  DebugBundleCaptureContext,
+  DebugBundleClient,
+  DebugBundleConfig,
+  DebugBundleLogLevel,
+  DebugBundleProbeOptions,
+  DebugBundleRequestInfo,
+  DebugBundleResponseInfo,
+  DebugBundleStatus
+} from "./types.js";
+
+const singleton = new DebugBundleReactNativeClient();
+
+export const DebugBundle = {
+  init(config: DebugBundleConfig): void {
+    singleton.init(config);
+    if (config.captureErrors !== false) {
+      installDebugBundleErrorHandlers(singleton, {
+        captureUnhandledRejections: config.captureUnhandledRejections !== false
+      });
+    }
+    if (config.captureConsole === true) {
+      captureDebugBundleConsole(singleton);
+    }
+  },
+  captureException(error: unknown, context?: DebugBundleCaptureContext): void {
+    singleton.captureException(error, context);
+  },
+  captureError(error: unknown, context?: DebugBundleCaptureContext): void {
+    singleton.captureError(error, context);
+  },
+  captureLog(message: string, level?: DebugBundleLogLevel, context?: DebugBundleCaptureContext): void {
+    singleton.captureLog(message, level, context);
+  },
+  captureRequest(request: DebugBundleRequestInfo, response: DebugBundleResponseInfo, context?: DebugBundleCaptureContext): void {
+    singleton.captureRequest(request, response, context);
+  },
+  captureMessage(message: string, level?: DebugBundleLogLevel, context?: DebugBundleCaptureContext): void {
+    singleton.captureMessage(message, level, context);
+  },
+  setContext(key: string, value: unknown): void {
+    singleton.setContext(key, value);
+  },
+  probe(label: string, data: unknown | (() => unknown), options?: DebugBundleProbeOptions): void {
+    singleton.probe(label, data, options);
+  },
+  flush(): Promise<void> {
+    return singleton.flush();
+  },
+  activateProbeTriggerToken(token: string): Promise<boolean> {
+    return singleton.activateProbeTriggerToken(token);
+  },
+  recordBreadcrumb(type: string, data?: Record<string, unknown>): void {
+    singleton.recordBreadcrumb(type, data);
+  },
+  recordScreen(screenName: string, previousScreen?: string | null, source?: string): void {
+    singleton.recordScreen(screenName, previousScreen, source);
+  },
+  get status(): DebugBundleStatus {
+    return singleton.status;
+  },
+  get lastEventAt(): number | null {
+    return singleton.lastEventAt;
+  }
+};
+
+export { createDebugBundleClient, DebugBundleReactNativeClient };
+export { captureDebugBundleConsole };
+export { installDebugBundleErrorHandlers };
+export type {
+  DebugBundleCaptureContext,
+  DebugBundleClient,
+  DebugBundleConfig,
+  DebugBundleLogLevel,
+  DebugBundleProbeOptions,
+  DebugBundleRequestInfo,
+  DebugBundleResponseInfo,
+  DebugBundleStatus
+};

package/src/native.ts

@@ -0,0 +1,79 @@
+import type { NativeDebugBundleModule, NativeDebugBundleState } from "./types.js";
+
+let overrideModule: NativeDebugBundleModule | null | undefined;
+let cachedReactNativeModule: NativeDebugBundleModule | null | undefined;
+
+export function getNativeModule(): NativeDebugBundleModule | null {
+  if (overrideModule !== undefined) {
+    return overrideModule;
+  }
+  const globalValue = globalThis as typeof globalThis & {
+    __DebugBundleReactNativeModule?: NativeDebugBundleModule;
+    nativeFabricUIManager?: unknown;
+  };
+  if (globalValue.__DebugBundleReactNativeModule) {
+    return globalValue.__DebugBundleReactNativeModule;
+  }
+  if (cachedReactNativeModule !== undefined) {
+    return cachedReactNativeModule;
+  }
+  cachedReactNativeModule = resolveReactNativeModule();
+  return cachedReactNativeModule;
+}
+
+export function setNativeModuleForTesting(module: NativeDebugBundleModule | null | undefined): void {
+  overrideModule = module;
+}
+
+export function degradedNativeState(reason: string): NativeDebugBundleState {
+  return {
+    status: "degraded",
+    lastEventAt: null,
+    device: null,
+    nativeModuleAvailable: false,
+    degradedReason: reason
+  };
+}
+
+export async function safeNativeCall<T>(operation: () => Promise<T> | T, fallback: T): Promise<T> {
+  try {
+    return await operation();
+  } catch {
+    return fallback;
+  }
+}
+
+export function resetNativeModuleCacheForTesting(): void {
+  cachedReactNativeModule = undefined;
+}
+
+function resolveReactNativeModule(): NativeDebugBundleModule | null {
+  const required = requireReactNative();
+  const turboModule = required?.TurboModuleRegistry?.get?.("DebugBundleReactNative") as NativeDebugBundleModule | null | undefined;
+  if (turboModule) {
+    return turboModule;
+  }
+  return (required?.NativeModules?.DebugBundleReactNative as NativeDebugBundleModule | undefined) ?? null;
+}
+
+function requireReactNative():
+  | {
+      NativeModules?: Record<string, unknown>;
+      TurboModuleRegistry?: { get?: (name: string) => unknown };
+    }
+  | null {
+  try {
+    const maybeRequire = Function("return typeof require === 'function' ? require : null")() as
+      | ((specifier: string) => unknown)
+      | null;
+    if (!maybeRequire) {
+      return null;
+    }
+    return maybeRequire("react-native") as {
+      NativeModules?: Record<string, unknown>;
+      TurboModuleRegistry?: { get?: (name: string) => unknown };
+    };
+  } catch {
+    return null;
+  }
+}

package/src/navigation.tsx

@@ -0,0 +1,37 @@
+import { DebugBundle } from "./index.js";
+import type { DebugBundleClient } from "./types.js";
+
+export interface DebugBundleNavigationRef {
+  current?: unknown;
+  getCurrentRoute?: () => { name?: string; key?: string; params?: unknown } | undefined;
+}
+
+let previousRouteName: string | null = null;
+
+export function createDebugBundleNavigationRef(): DebugBundleNavigationRef {
+  return { current: undefined };
+}
+
+export function onDebugBundleNavigationReady(ref: DebugBundleNavigationRef, client: DebugBundleClient = DebugBundle): void {
+  previousRouteName = routeName(ref);
+  if (previousRouteName) {
+    client.recordScreen(previousRouteName, null, "react-navigation");
+  }
+}
+
+export function onDebugBundleNavigationStateChange(ref: DebugBundleNavigationRef, client: DebugBundleClient = DebugBundle): void {
+  const currentRouteName = routeName(ref);
+  if (!currentRouteName || currentRouteName === previousRouteName) {
+    return;
+  }
+  client.recordScreen(currentRouteName, previousRouteName, "react-navigation");
+  previousRouteName = currentRouteName;
+}
+
+function routeName(ref: DebugBundleNavigationRef): string | null {
+  const route = ref.getCurrentRoute?.();
+  if (!route?.name) {
+    return null;
+  }
+  return route.name.replace(/[^a-zA-Z0-9_.:/-]/g, "_").slice(0, 120);
+}

package/src/network.ts

@@ -0,0 +1,240 @@
+import { DebugBundle } from "./index.js";
+import { sanitizeHeaders } from "./redaction.js";
+import type { DebugBundleClient, DebugBundleConfig, DebugBundleNetworkFilter } from "./types.js";
+
+const TRACE_HEADER = "X-DebugBundle-Trace-Id";
+let fetchRestore: (() => void) | null = null;
+let xhrRestore: (() => void) | null = null;
+
+export interface NetworkInstrumentationOptions {
+  client?: DebugBundleClient;
+  tracePropagationTargets?: string[];
+  captureNetwork?: boolean;
+  networkFilter?: DebugBundleNetworkFilter;
+  headerAllowlist?: string[];
+  redactFields?: string[];
+}
+
+export function instrumentDebugBundleNetwork(options: NetworkInstrumentationOptions = {}): () => void {
+  const client = options.client ?? DebugBundle;
+  const fetchTarget = globalThis as typeof globalThis & { fetch?: typeof fetch; XMLHttpRequest?: typeof XMLHttpRequest };
+  if (fetchTarget.fetch && !fetchRestore) {
+    const originalFetch = fetchTarget.fetch.bind(globalThis);
+    fetchTarget.fetch = createInstrumentedFetch(originalFetch, client, options) as typeof fetch;
+    fetchRestore = () => {
+      fetchTarget.fetch = originalFetch;
+      fetchRestore = null;
+    };
+  }
+  if (fetchTarget.XMLHttpRequest && !xhrRestore) {
+    xhrRestore = instrumentXMLHttpRequest(fetchTarget.XMLHttpRequest, client, options);
+  }
+  return () => {
+    fetchRestore?.();
+    xhrRestore?.();
+  };
+}
+
+export function createInstrumentedFetch(
+  originalFetch: typeof fetch,
+  client: Pick<DebugBundleClient, "captureRequest">,
+  options: NetworkInstrumentationOptions
+): typeof fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const startedAt = Date.now();
+    const url = requestUrl(input);
+    const method = requestMethod(input, init);
+    const traceId = shouldInjectTrace(url, options.tracePropagationTargets ?? []) ? existingTraceHeader(input, init) ?? generateTraceId() : null;
+    const nextInit = traceId ? withTraceHeader(init, traceId) : init;
+    try {
+      const response = await originalFetch(input, nextInit);
+      maybeCaptureNetwork(client, options, url, method, traceId, response.status, Date.now() - startedAt, headersToRecord(nextInit?.headers));
+      return response;
+    } catch (error) {
+      maybeCaptureNetwork(client, options, url, method, traceId, 0, Date.now() - startedAt, headersToRecord(nextInit?.headers));
+      throw error;
+    }
+  }) as typeof fetch;
+}
+
+export function shouldInjectTrace(url: string, targets: string[]): boolean {
+  if (isRelativeUrl(url)) {
+    return true;
+  }
+  return targets.some((target) => matchesTarget(url, target));
+}
+
+function instrumentXMLHttpRequest(
+  OriginalXHR: typeof XMLHttpRequest,
+  client: DebugBundleClient,
+  options: NetworkInstrumentationOptions
+): () => void {
+  const proto = OriginalXHR.prototype as XMLHttpRequest & {
+    __debugBundleWrapped?: boolean;
+    __debugBundleUrl?: string;
+    __debugBundleMethod?: string;
+    __debugBundleStartedAt?: number;
+    __debugBundleTraceId?: string | null;
+  };
+  if (proto.__debugBundleWrapped) {
+    return () => undefined;
+  }
+  const originalOpen = proto.open;
+  const originalSend = proto.send;
+  const originalSetRequestHeader = proto.setRequestHeader;
+  proto.open = function open(method: string, url: string | URL) {
+    this.__debugBundleMethod = method;
+    this.__debugBundleUrl = String(url);
+    return originalOpen.apply(this, arguments as unknown as Parameters<typeof originalOpen>);
+  };
+  proto.send = function send() {
+    const url = this.__debugBundleUrl ?? "";
+    const traceId = shouldInjectTrace(url, options.tracePropagationTargets ?? []) ? generateTraceId() : null;
+    this.__debugBundleTraceId = traceId;
+    this.__debugBundleStartedAt = Date.now();
+    if (traceId) {
+      originalSetRequestHeader.call(this, TRACE_HEADER, traceId);
+    }
+    this.addEventListener("loadend", () => {
+      maybeCaptureNetwork(
+        client,
+        options,
+        url,
+        this.__debugBundleMethod ?? "GET",
+        this.__debugBundleTraceId ?? null,
+        this.status,
+        Date.now() - (this.__debugBundleStartedAt ?? Date.now()),
+        traceId ? { [TRACE_HEADER]: traceId } : {}
+      );
+    });
+    return originalSend.apply(this, arguments as unknown as Parameters<typeof originalSend>);
+  };
+  proto.__debugBundleWrapped = true;
+  return () => {
+    proto.open = originalOpen;
+    proto.send = originalSend;
+    proto.__debugBundleWrapped = false;
+  };
+}
+
+function maybeCaptureNetwork(
+  client: Pick<DebugBundleClient, "captureRequest">,
+  options: NetworkInstrumentationOptions,
+  url: string,
+  method: string,
+  traceId: string | null,
+  statusCode: number,
+  durationMillis: number,
+  headers: Record<string, string>
+): void {
+  if (options.captureNetwork === false || !matchesNetworkFilter(url, statusCode, durationMillis, options.networkFilter)) {
+    return;
+  }
+  const sanitizeOptions = options.redactFields ? { redactFields: options.redactFields } : {};
+  client.captureRequest(
+    {
+      method,
+      url,
+      headers: sanitizeHeaders(headers, options.headerAllowlist, sanitizeOptions),
+      ...(traceId ? { traceId } : {})
+    },
+    { statusCode, durationMillis },
+    traceId ? { trace_id: traceId } : undefined
+  );
+}
+
+function matchesNetworkFilter(url: string, statusCode: number, durationMillis: number, filter: DebugBundleNetworkFilter = {}): boolean {
+  if (filter.urlDenylist?.some((entry) => url.includes(entry))) {
+    return false;
+  }
+  if (filter.urlAllowlist && filter.urlAllowlist.length > 0 && !filter.urlAllowlist.some((entry) => url.includes(entry))) {
+    return false;
+  }
+  if (filter.statusCodes && filter.statusCodes.length > 0 && !filter.statusCodes.includes(statusCode)) {
+    return false;
+  }
+  if (filter.minResponseTime !== undefined && durationMillis < filter.minResponseTime) {
+    return false;
+  }
+  return statusCode === 0 || statusCode >= 400 || filter.statusCodes !== undefined || filter.minResponseTime !== undefined;
+}
+
+function requestUrl(input: RequestInfo | URL): string {
+  if (typeof input === "string") {
+    return input;
+  }
+  if (input instanceof URL) {
+    return input.toString();
+  }
+  return "url" in input ? input.url : String(input);
+}
+
+function requestMethod(input: RequestInfo | URL, init?: RequestInit): string {
+  if (init?.method) {
+    return init.method.toUpperCase();
+  }
+  if (typeof input === "object" && "method" in input && typeof input.method === "string") {
+    return input.method.toUpperCase();
+  }
+  return "GET";
+}
+
+function withTraceHeader(init: RequestInit | undefined, traceId: string): RequestInit {
+  const headers = new Headers(init?.headers);
+  if (!headers.has(TRACE_HEADER)) {
+    headers.set(TRACE_HEADER, traceId);
+  }
+  return { ...init, headers };
+}
+
+function existingTraceHeader(input: RequestInfo | URL, init?: RequestInit): string | null {
+  const fromInit = init?.headers ? new Headers(init.headers).get(TRACE_HEADER) : null;
+  if (fromInit) {
+    return fromInit;
+  }
+  if (typeof input === "object" && "headers" in input) {
+    return new Headers(input.headers).get(TRACE_HEADER);
+  }
+  return null;
+}
+
+function headersToRecord(headers: HeadersInit | undefined): Record<string, string> {
+  const output: Record<string, string> = {};
+  if (!headers) {
+    return output;
+  }
+  new Headers(headers).forEach((value, key) => {
+    output[key] = value;
+  });
+  return output;
+}
+
+function isRelativeUrl(url: string): boolean {
+  return url.startsWith("/") && !url.startsWith("//");
+}
+
+function matchesTarget(url: string, target: string): boolean {
+  if (!target || target.includes("*")) {
+    return false;
+  }
+  try {
+    const parsedUrl = new URL(url);
+    const parsedTarget = new URL(target);
+    return parsedUrl.origin === parsedTarget.origin && parsedUrl.pathname.startsWith(parsedTarget.pathname.replace(/\/$/, ""));
+  } catch {
+    return false;
+  }
+}
+
+function generateTraceId(): string {
+  if (globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (marker) => {
+    const random = Math.trunc(Math.random() * 16);
+    const value = marker === "x" ? random : (random & 0x3) | 0x8;
+    return value.toString(16);
+  });
+}
+
+export type { DebugBundleConfig };

package/src/probes.ts

@@ -0,0 +1,11 @@
+import { DebugBundle } from "./index.js";
+import type { DebugBundleClient, DebugBundleProbeOptions } from "./types.js";
+
+export function probe(label: string, data: unknown | (() => unknown), options?: DebugBundleProbeOptions): void {
+  DebugBundle.probe(label, data, options);
+}
+
+export function activateDebugBundleProbeTrigger(token: string, client: DebugBundleClient = DebugBundle): boolean {
+  void client.activateProbeTriggerToken(token);
+  return Boolean(token);
+}

package/src/react-native-shim.d.ts

@@ -0,0 +1,14 @@
+declare module "react-native" {
+  export interface TurboModule {}
+
+  export const TurboModuleRegistry: {
+    get<T extends TurboModule>(name: string): T | null;
+    getEnforcing<T extends TurboModule>(name: string): T;
+  };
+
+  export const NativeModules: Record<string, unknown>;
+}
+
+declare module "react-native/Libraries/Types/CodegenTypes" {
+  export type UnsafeObject = object;
+}

package/src/react.tsx

@@ -0,0 +1,60 @@
+import * as React from "react";
+import { DebugBundle } from "./index.js";
+import type { DebugBundleClient } from "./types.js";
+
+export interface DebugBundleErrorBoundaryProps {
+  children: React.ReactNode;
+  client?: DebugBundleClient;
+  fallback?: React.ReactNode | ((error: Error) => React.ReactNode);
+  context?: Record<string, unknown>;
+  rethrow?: boolean;
+}
+
+interface DebugBundleErrorBoundaryState {
+  error: Error | null;
+}
+
+export class DebugBundleErrorBoundary extends React.Component<
+  DebugBundleErrorBoundaryProps,
+  DebugBundleErrorBoundaryState
+> {
+  state: DebugBundleErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): DebugBundleErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    const client = this.props.client ?? DebugBundle;
+    client.captureException(error, {
+      ...this.props.context,
+      component_stack: info.componentStack,
+      source: "react-error-boundary"
+    });
+    if (this.props.rethrow) {
+      throw error;
+    }
+  }
+
+  render(): React.ReactNode {
+    if (!this.state.error) {
+      return this.props.children;
+    }
+    if (typeof this.props.fallback === "function") {
+      return this.props.fallback(this.state.error);
+    }
+    return this.props.fallback ?? null;
+  }
+}
+
+export function useDebugBundleAction(
+  actionName: string,
+  client: DebugBundleClient = DebugBundle
+): (data?: Record<string, unknown>) => void {
+  return (data?: Record<string, unknown>) => {
+    client.recordBreadcrumb("action", {
+      action_name: actionName,
+      ...(data ?? {})
+    });
+  };
+}