@debugbundle/sdk-react-native 0.1.0

package/ios/DebugBundleReactNative.swift

@@ -0,0 +1,125 @@
+import Foundation
+import React
+import DebugBundle
+
+@objc(DebugBundleReactNative)
+final class DebugBundleReactNative: NSObject {
+	@objc(initialize:resolver:rejecter:)
+	func initialize(
+		_ config: NSDictionary,
+		resolver resolve: @escaping RCTPromiseResolveBlock,
+		rejecter reject: @escaping RCTPromiseRejectBlock
+	) {
+		let sdkConfig = DebugBundleConfig(
+			projectToken: config["projectToken"] as? String ?? "",
+			enabled: config["enabled"] as? Bool ?? true,
+			environment: config["environment"] as? String ?? "production",
+			service: config["service"] as? String ?? "react-native-app",
+			endpoint: URL(string: config["endpoint"] as? String ?? DebugBundleConfig.defaultEndpoint.absoluteString) ?? DebugBundleConfig.defaultEndpoint,
+			releaseChannel: config["releaseChannel"] as? String ?? "production",
+			appVersion: config["appVersion"] as? String,
+			buildNumber: config["buildNumber"] as? String,
+			sdkVersion: config["sdkVersion"] as? String ?? "0.1.0"
+		)
+		DebugBundle.initialize(sdkConfig, transport: DebugBundleHTTPTransport())
+		resolve(state())
+	}
+
+	@objc(enqueueEvent:resolver:rejecter:)
+	func enqueueEvent(
+		_ event: NSDictionary,
+		resolver resolve: @escaping RCTPromiseResolveBlock,
+		rejecter reject: @escaping RCTPromiseRejectBlock
+	) {
+		let eventType = event["event_type"] as? String ?? "unknown"
+		let payload = event["payload"] as? [String: Any?] ?? [:]
+		switch eventType {
+		case "frontend_exception":
+			DebugBundle.captureException(NSError(domain: "DebugBundleReactNative", code: 1, userInfo: payload.compactMapValues { $0 }))
+		case "frontend_breadcrumb":
+			DebugBundle.recordBreadcrumb(payload["breadcrumb_type"] as? String ?? "react_native", data: payload)
+		case "log_event":
+			DebugBundle.captureLog(payload["message"] as? String ?? "", level: logLevel(payload["level"] as? String), context: payload)
+		case "request_event":
+			let correlation = event["correlation"] as? [String: Any?]
+			DebugBundle.captureRequest(
+				DebugBundleRequestInfo(
+					method: payload["method"] as? String ?? "GET",
+					url: payload["url"] as? String ?? "",
+					routeTemplate: payload["route_template"] as? String,
+					traceId: correlation?["trace_id"] as? String
+				),
+				response: DebugBundleResponseInfo(
+					statusCode: payload["response_status"] as? Int ?? 0,
+					durationMillis: payload["duration_ms"] as? Int
+				),
+				context: payload
+			)
+		default:
+			DebugBundle.captureMessage("react_native_event:\(eventType)", context: payload)
+		}
+		resolve(nil)
+	}
+
+	@objc(flush:rejecter:)
+	func flush(resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+		Task {
+			await DebugBundle.flush()
+			resolve(nil)
+		}
+	}
+
+	@objc(getStatus:rejecter:)
+	func getStatus(resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+		resolve(state())
+	}
+
+	@objc(setContext:value:resolver:rejecter:)
+	func setContext(
+		_ key: String,
+		value: Any?,
+		resolver resolve: @escaping RCTPromiseResolveBlock,
+		rejecter reject: @escaping RCTPromiseRejectBlock
+	) {
+		DebugBundle.setContext(key, value: value)
+		resolve(nil)
+	}
+
+	@objc(activateProbeTriggerToken:resolver:rejecter:)
+	func activateProbeTriggerToken(
+		_ token: String,
+		resolver resolve: @escaping RCTPromiseResolveBlock,
+		rejecter reject: @escaping RCTPromiseRejectBlock
+	) {
+		resolve(DebugBundle.activateProbeTriggerToken(token))
+	}
+
+	@objc
+	static func requiresMainQueueSetup() -> Bool {
+		false
+	}
+
+	private func state() -> [String: Any?] {
+		[
+			"status": DebugBundle.status.rawValue,
+			"lastEventAt": DebugBundle.lastEventAt.map { $0.timeIntervalSince1970 * 1000 },
+			"nativeModuleAvailable": true,
+			"degradedReason": nil
+		]
+	}
+}
+
+private func logLevel(_ value: String?) -> DebugBundleLogLevel {
+	switch value?.lowercased() {
+	case "debug":
+		return .debug
+	case "info":
+		return .info
+	case "error":
+		return .error
+	case "critical":
+		return .critical
+	default:
+		return .warning
+	}
+}

package/ios/DebugBundleReactNativeBridge.m

@@ -0,0 +1,28 @@
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(DebugBundleReactNative, NSObject)
+
+RCT_EXTERN_METHOD(initialize:(NSDictionary *)config
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(enqueueEvent:(NSDictionary *)event
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(flush:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getStatus:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(setContext:(NSString *)key
+                  value:(id)value
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(activateProbeTriggerToken:(NSString *)token
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@debugbundle/sdk-react-native",
+  "version": "0.1.0",
+  "description": "React Native SDK for DebugBundle mobile event capture.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "homepage": "https://github.com/debugbundle/debugbundle-react-native#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/debugbundle/debugbundle-react-native.git"
+  },
+  "bugs": {
+    "url": "https://github.com/debugbundle/debugbundle-react-native/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "react-native": "./src/index.ts",
+  "codegenConfig": {
+    "name": "DebugBundleReactNativeSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.debugbundle.reactnative"
+    },
+    "ios": {
+      "modulesProvider": {
+        "DebugBundleReactNative": "DebugBundleReactNative"
+      }
+    }
+  },
+  "files": [
+    "android/build.gradle",
+    "android/src",
+    "ios",
+    "src",
+    "dist",
+    "app.plugin.js",
+    "DebugBundleReactNative.podspec",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./network": {
+      "types": "./dist/network.d.ts",
+      "default": "./dist/network.js"
+    },
+    "./navigation": {
+      "types": "./dist/navigation.d.ts",
+      "default": "./dist/navigation.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./console": {
+      "types": "./dist/console.d.ts",
+      "default": "./dist/console.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@expo/config-plugins": ">=9",
+    "@react-navigation/native": ">=6",
+    "react": ">=18",
+    "react-native": ">=0.84"
+  },
+  "peerDependenciesMeta": {
+    "@expo/config-plugins": {
+      "optional": true
+    },
+    "@react-navigation/native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/src/NativeDebugBundleReactNative.ts

@@ -0,0 +1,14 @@
+import type { TurboModule } from "react-native";
+import type { UnsafeObject } from "react-native/Libraries/Types/CodegenTypes";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+  initialize(config: UnsafeObject): Promise<UnsafeObject>;
+  enqueueEvent(event: UnsafeObject): Promise<void>;
+  flush(): Promise<void>;
+  getStatus(): Promise<UnsafeObject>;
+  setContext(key: string, value: unknown): Promise<void>;
+  activateProbeTriggerToken?(token: string): Promise<boolean>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("DebugBundleReactNative");

package/src/app-state.ts

@@ -0,0 +1,17 @@
+import { DebugBundle } from "./index.js";
+import type { DebugBundleClient } from "./types.js";
+
+export interface AppStateLike {
+  currentState?: string;
+  addEventListener(event: "change", listener: (state: string) => void): { remove: () => void };
+}
+
+export function instrumentDebugBundleAppState(appState: AppStateLike, client: DebugBundleClient = DebugBundle): () => void {
+  const subscription = appState.addEventListener("change", (state) => {
+    client.recordBreadcrumb("app_state", { state });
+    if (state === "background" || state === "inactive") {
+      void client.flush();
+    }
+  });
+  return () => subscription.remove();
+}

package/src/client.ts

@@ -0,0 +1,385 @@
+import { getNativeModule, degradedNativeState, safeNativeCall } from "./native.js";
+import { defaultRedactFields, DEFAULT_HEADER_ALLOWLIST, sanitizeHeaders, sanitizeValue } from "./redaction.js";
+import type {
+  DebugBundleCaptureContext,
+  DebugBundleClient,
+  DebugBundleConfig,
+  DebugBundleEventEnvelope,
+  DebugBundleLogLevel,
+  DebugBundleProbeOptions,
+  DebugBundleRequestInfo,
+  DebugBundleResponseInfo,
+  DebugBundleStatus,
+  NativeDebugBundleModule,
+  NativeDebugBundleState,
+  ResolvedDebugBundleConfig
+} from "./types.js";
+
+const SDK_NAME = "@debugbundle/sdk-react-native" as const;
+const DEFAULT_SDK_VERSION = "0.1.0";
+const LOG_LEVELS: Record<DebugBundleLogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warning: 30,
+  error: 40,
+  critical: 50
+};
+
+export class DebugBundleReactNativeClient implements DebugBundleClient {
+  private config: ResolvedDebugBundleConfig;
+  private nativeModule: NativeDebugBundleModule | null = null;
+  private nativeState: NativeDebugBundleState = degradedNativeState("not_initialized");
+  private context: Record<string, unknown> = {};
+  private breadcrumbs: Array<Record<string, unknown>> = [];
+  private probeBuffers = new Map<string, Array<Record<string, unknown>>>();
+  private jsProbeActivationExpiresAt = 0;
+  private sessionSampledIn = true;
+  private sessionEventCount = 0;
+
+  constructor(config: DebugBundleConfig = {}) {
+    this.config = resolveConfig(config);
+    if (Object.keys(config).length > 0) {
+      this.init(config);
+    }
+  }
+
+  get status(): DebugBundleStatus {
+    return this.nativeState.status;
+  }
+
+  get lastEventAt(): number | null {
+    return this.nativeState.lastEventAt ?? null;
+  }
+
+  init(config: DebugBundleConfig): void {
+    this.config = resolveConfig(config);
+    this.nativeModule = getNativeModule();
+    this.sessionSampledIn =
+      this.config.enabled &&
+      (this.config.sessionSampleRate >= 1 || Math.random() <= this.config.sessionSampleRate);
+    if (!this.config.enabled) {
+      this.nativeState = { status: "disconnected", lastEventAt: null, nativeModuleAvailable: Boolean(this.nativeModule) };
+      return;
+    }
+    if (!this.config.projectToken || !this.config.endpoint) {
+      this.nativeState = degradedNativeState("missing_project_token_or_endpoint");
+      return;
+    }
+    if (!this.nativeModule) {
+      this.nativeState = degradedNativeState("native_module_unavailable");
+      return;
+    }
+    void safeNativeCall(
+      async () => {
+        this.nativeState = await this.nativeModule!.initialize(this.config);
+        if (!this.nativeState.status) {
+          this.nativeState.status = "healthy";
+        }
+      },
+      undefined
+    );
+    this.nativeState = { status: "healthy", lastEventAt: null, nativeModuleAvailable: true };
+  }
+
+  captureException(error: unknown, context: DebugBundleCaptureContext = {}): void {
+    const mergedContext = this.mergeContext(context);
+    this.enqueue("frontend_exception", {
+      error: sanitizeValue(error, { redactFields: this.config.redactFields }),
+      context: sanitizeValue(mergedContext, { redactFields: this.config.redactFields }),
+      breadcrumbs: this.breadcrumbs.slice(),
+      probe_data: this.snapshotProbeData()
+    }, stringValue(mergedContext.trace_id), false);
+  }
+
+  captureError(error: unknown, context: DebugBundleCaptureContext = {}): void {
+    this.captureException(error, context);
+  }
+
+  captureLog(message: string, level: DebugBundleLogLevel = "warning", context: DebugBundleCaptureContext = {}): void {
+    if (!this.config.captureLogs || LOG_LEVELS[level] < LOG_LEVELS[this.config.logLevel]) {
+      return;
+    }
+    this.enqueue("log_event", {
+      level,
+      message: sanitizeValue(message, { redactFields: this.config.redactFields }),
+      context: sanitizeValue(this.mergeContext(context), { redactFields: this.config.redactFields }),
+      source: "javascript"
+    }, stringValue(context.trace_id), true);
+  }
+
+  captureRequest(
+    request: DebugBundleRequestInfo,
+    response: DebugBundleResponseInfo,
+    context: DebugBundleCaptureContext = {}
+  ): void {
+    const traceId = request.traceId ?? stringValue(context.trace_id);
+    const payload = {
+      method: request.method,
+      url: sanitizeUrl(request.url),
+      route_template: request.routeTemplate ?? null,
+      request_headers: sanitizeHeaders(request.headers, this.config.headerAllowlist, {
+        redactFields: this.config.redactFields
+      }),
+      response_status: response.statusCode,
+      response_headers: sanitizeHeaders(response.headers, this.config.headerAllowlist, {
+        redactFields: this.config.redactFields
+      }),
+      duration_ms: response.durationMillis ?? null,
+      source: "react-native"
+    };
+    this.recordBreadcrumb("network", payload);
+    if (this.shouldCaptureRequestEvent(response.statusCode)) {
+      this.enqueue("request_event", payload, traceId, true);
+    }
+  }
+
+  captureMessage(message: string, level: DebugBundleLogLevel = "warning", context: DebugBundleCaptureContext = {}): void {
+    this.recordBreadcrumb("message", {
+      level,
+      message: sanitizeValue(message, { redactFields: this.config.redactFields }),
+      context: sanitizeValue(this.mergeContext(context), { redactFields: this.config.redactFields })
+    });
+  }
+
+  setContext(key: string, value: unknown): void {
+    this.context[key] = sanitizeValue(value, { redactFields: this.config.redactFields });
+    if (this.nativeModule?.setContext) {
+      void safeNativeCall(() => this.nativeModule!.setContext!(key, this.context[key]), undefined);
+    }
+  }
+
+  probe(label: string, data: unknown | (() => unknown), options: DebugBundleProbeOptions = {}): void {
+    if (!label || this.probeBuffers.size >= this.config.maxProbeLabels && !this.probeBuffers.has(label)) {
+      return;
+    }
+    if (options.heavy && !this.hasActiveJsProbeActivation()) {
+      return;
+    }
+    const value = typeof data === "function" ? safeInvoke(data as () => unknown) : data;
+    const entry = {
+      label,
+      data: sanitizeValue(value, { redactFields: this.config.redactFields }),
+      timestamp: new Date().toISOString(),
+      activation_id: null
+    };
+    const entries = this.probeBuffers.get(label) ?? [];
+    entries.push(entry);
+    this.probeBuffers.set(label, entries.slice(-this.config.maxProbeEntriesPerLabel));
+  }
+
+  async flush(): Promise<void> {
+    if (!this.nativeModule) {
+      return;
+    }
+    await safeNativeCall(async () => {
+      await this.nativeModule!.flush();
+      const state = await this.nativeModule!.getStatus();
+      this.nativeState = state;
+    }, undefined);
+  }
+
+  async activateProbeTriggerToken(token: string): Promise<boolean> {
+    if (!this.nativeModule?.activateProbeTriggerToken) {
+      return false;
+    }
+    const activated = await safeNativeCall(() => this.nativeModule!.activateProbeTriggerToken!(token), false);
+    if (activated) {
+      this.jsProbeActivationExpiresAt = Date.now() + 60 * 60 * 1000;
+    }
+    return activated;
+  }
+
+  recordBreadcrumb(type: string, data: Record<string, unknown> = {}): void {
+    this.breadcrumbs.push({
+      breadcrumb_type: type,
+      occurred_at: new Date().toISOString(),
+      data: sanitizeValue(data, { redactFields: this.config.redactFields })
+    });
+    this.breadcrumbs = this.breadcrumbs.slice(-this.config.maxBreadcrumbs);
+  }
+
+  recordScreen(screenName: string, previousScreen: string | null = null, source = "react-navigation"): void {
+    if (!this.config.captureScreens) {
+      return;
+    }
+    this.recordBreadcrumb("screen", {
+      screen_name: sanitizeScreenName(screenName),
+      previous_screen: previousScreen ? sanitizeScreenName(previousScreen) : null,
+      source
+    });
+  }
+
+  private enqueue(
+    eventType: DebugBundleEventEnvelope["event_type"],
+    payload: Record<string, unknown>,
+    traceId: string | null,
+    countTowardSession: boolean
+  ): void {
+    if (!this.canCapture(eventType, countTowardSession)) {
+      return;
+    }
+    const event: DebugBundleEventEnvelope = {
+      schema_version: "1",
+      event_id: generateId(),
+      event_type: eventType,
+      sdk_name: SDK_NAME,
+      sdk_version: this.config.sdkVersion,
+      service: {
+        name: this.config.service,
+        environment: this.config.environment,
+        runtime: "react-native",
+        framework: "react-native"
+      },
+      occurred_at: new Date().toISOString(),
+      correlation: traceId ? { trace_id: traceId } : null,
+      payload,
+      device: this.nativeState.device ?? deviceFromConfig(this.config)
+    };
+    if (countTowardSession) {
+      this.sessionEventCount += 1;
+    }
+    if (!this.nativeModule) {
+      this.nativeState = degradedNativeState("native_module_unavailable");
+      return;
+    }
+    void safeNativeCall(() => this.nativeModule!.enqueueEvent(event), undefined);
+  }
+
+  private canCapture(eventType: DebugBundleEventEnvelope["event_type"], countTowardSession: boolean): boolean {
+    if (!this.config.enabled || !this.config.projectToken || !this.sessionSampledIn) {
+      return false;
+    }
+    if (Math.random() > this.config.sampleRate) {
+      return false;
+    }
+    if (countTowardSession && this.sessionEventCount >= this.config.maxEventsPerSession) {
+      return eventType === "frontend_exception" || eventType === "probe_event";
+    }
+    return true;
+  }
+
+  private mergeContext(context: DebugBundleCaptureContext): Record<string, unknown> {
+    return { ...this.context, ...context };
+  }
+
+  private snapshotProbeData(): Record<string, unknown> {
+    if (!this.config.probeFlushOnError) {
+      return { version: 1, items: [] };
+    }
+    return {
+      version: 1,
+      items: [...this.probeBuffers.values()].flat()
+    };
+  }
+
+  private hasActiveJsProbeActivation(): boolean {
+    return this.jsProbeActivationExpiresAt > Date.now();
+  }
+
+  private shouldCaptureRequestEvent(statusCode: number): boolean {
+    return statusCode >= 500 || [408, 423, 424, 425, 429].includes(statusCode);
+  }
+}
+
+export function createDebugBundleClient(config: DebugBundleConfig = {}): DebugBundleReactNativeClient {
+  return new DebugBundleReactNativeClient(config);
+}
+
+export function resolveConfig(config: DebugBundleConfig): ResolvedDebugBundleConfig {
+  return {
+    projectToken: config.projectToken ?? "",
+    enabled: config.enabled ?? true,
+    environment: config.environment ?? "production",
+    service: config.service ?? "react-native-app",
+    endpoint: config.endpoint ?? "https://api.debugbundle.com/v1/events",
+    releaseChannel: config.releaseChannel ?? "production",
+    appVersion: config.appVersion ?? null,
+    buildNumber: config.buildNumber ?? null,
+    batchSize: clampInteger(config.batchSize, 10, 1, 100),
+    flushInterval: clampInteger(config.flushInterval, 3000, 100, 60000),
+    sampleRate: clampRate(config.sampleRate),
+    sessionSampleRate: clampRate(config.sessionSampleRate),
+    maxEventsPerSession: clampInteger(config.maxEventsPerSession, 100, 1, 10000),
+    maxBreadcrumbs: clampInteger(config.maxBreadcrumbs, 20, 1, 200),
+    captureErrors: config.captureErrors ?? true,
+    captureUnhandledRejections: config.captureUnhandledRejections ?? true,
+    captureScreens: config.captureScreens ?? true,
+    captureActions: config.captureActions ?? false,
+    captureNetwork: config.captureNetwork ?? true,
+    captureConsole: config.captureConsole ?? false,
+    captureLogs: config.captureLogs ?? true,
+    logLevel: config.logLevel ?? "warning",
+    tracePropagationTargets: config.tracePropagationTargets ?? [],
+    networkFilter: config.networkFilter ?? {},
+    offlineQueueMaxEvents: clampInteger(config.offlineQueueMaxEvents, 500, 1, 10000),
+    offlineQueueMaxBytes: clampInteger(config.offlineQueueMaxBytes, 5 * 1024 * 1024, 1024, 100 * 1024 * 1024),
+    offlineQueueTtl: clampInteger(config.offlineQueueTtl, 72 * 60 * 60 * 1000, 60000, 30 * 24 * 60 * 60 * 1000),
+    requestTimeout: clampInteger(config.requestTimeout, 5000, 100, 60000),
+    maxProbeLabels: clampInteger(config.maxProbeLabels, 50, 1, 500),
+    maxProbeEntriesPerLabel: clampInteger(config.maxProbeEntriesPerLabel, 10, 1, 200),
+    probeFlushOnError: config.probeFlushOnError ?? true,
+    redactFields: config.redactFields ?? defaultRedactFields(),
+    headerAllowlist: config.headerAllowlist ?? DEFAULT_HEADER_ALLOWLIST,
+    sdkVersion: config.sdkVersion ?? DEFAULT_SDK_VERSION
+  };
+}
+
+function clampInteger(value: number | undefined, fallback: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, Math.trunc(value!)));
+}
+
+function clampRate(value: number | undefined): number {
+  if (!Number.isFinite(value)) {
+    return 1;
+  }
+  return Math.min(1, Math.max(0, value!));
+}
+
+function safeInvoke(producer: () => unknown): unknown {
+  try {
+    return producer();
+  } catch (error) {
+    return { error: sanitizeValue(error) };
+  }
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function sanitizeUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.search = "";
+    return parsed.toString();
+  } catch {
+    return url.split("?")[0] ?? url;
+  }
+}
+
+function sanitizeScreenName(screenName: string): string {
+  return screenName.replace(/[^a-zA-Z0-9_.:/-]/g, "_").slice(0, 120);
+}
+
+function generateId(): string {
+  const cryptoLike = globalThis.crypto;
+  if (cryptoLike?.randomUUID) {
+    return cryptoLike.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);
+  });
+}
+
+function deviceFromConfig(config: ResolvedDebugBundleConfig): Record<string, unknown> {
+  return {
+    app_version: config.appVersion,
+    build_number: config.buildNumber,
+    release_channel: config.releaseChannel
+  };
+}