@crumbsdk/react-native 0.0.1-rc.3

package/src/CrumbReactNative.nitro.ts

@@ -0,0 +1,12 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+export interface CrumbReactNative extends HybridObject<{
+  ios: 'swift';
+  android: 'kotlin';
+}> {
+  start(configurationJson: string): void;
+  installReporter(): Promise<boolean>;
+  show(): Promise<boolean>;
+  addLog(entryJson: string): void;
+  clearLogs(): void;
+}

package/src/NativeCrumbReactNative.ts

@@ -0,0 +1,6 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { CrumbReactNative } from './CrumbReactNative.nitro';
+
+export default NitroModules.createHybridObject<CrumbReactNative>(
+  'CrumbReactNative'
+);

package/src/NativeCrumbReactNative.web.ts

@@ -0,0 +1,20 @@
+import type { CrumbReactNative } from './CrumbReactNative.nitro';
+
+const unsupportedMessage =
+  'Crumb requires an iOS or Android native build and is unavailable on web or in Expo Go.';
+
+const unsupportedModule: CrumbReactNative = {
+  name: 'CrumbReactNative',
+  dispose: () => undefined,
+  equals: () => false,
+  toString: () => '[HybridObject CrumbReactNative unavailable on web]',
+  start: () => {
+    throw new Error(unsupportedMessage);
+  },
+  installReporter: () => Promise.resolve(false),
+  show: () => Promise.resolve(false),
+  addLog: () => undefined,
+  clearLogs: () => undefined,
+};
+
+export default unsupportedModule;

package/src/index.ts

@@ -0,0 +1,115 @@
+import NativeCrumbReactNative from './NativeCrumbReactNative';
+import {
+  clearLogs,
+  configureLogBuffer,
+  disableConsoleCapture,
+  enableConsoleCapture,
+  markNativeStarted,
+  writeLog,
+} from './log-buffer';
+import type {
+  CrumbConfiguration,
+  CrumbLogLevel,
+  CrumbLogMetadata,
+} from './types';
+
+export type {
+  CrumbCaptureOptions,
+  CrumbConfiguration,
+  CrumbDiagnosticsOptions,
+  CrumbInvocation,
+  CrumbLogLevel,
+  CrumbLogMetadata,
+  CrumbLogOptions,
+  CrumbPrivacyOptions,
+  CrumbRelease,
+  CrumbUploadOptions,
+} from './types';
+
+export async function start(configuration: CrumbConfiguration): Promise<void> {
+  validateConfiguration(configuration);
+  const logOptions = configuration.diagnostics?.logs;
+  configureLogBuffer(logOptions);
+  NativeCrumbReactNative.start(JSON.stringify(configuration));
+  markNativeStarted();
+
+  if (logOptions?.captureConsole) {
+    enableConsoleCapture();
+  } else {
+    disableConsoleCapture();
+  }
+}
+
+export function installReporter(): Promise<boolean> {
+  return NativeCrumbReactNative.installReporter();
+}
+
+export function show(): Promise<boolean> {
+  return NativeCrumbReactNative.show();
+}
+
+export function log(
+  level: CrumbLogLevel,
+  message: string,
+  metadata?: CrumbLogMetadata
+): void {
+  if (!message.trim()) {
+    throw new TypeError('Crumb.log message must not be empty.');
+  }
+  writeLog(level, message, metadata);
+}
+
+export { clearLogs, disableConsoleCapture, enableConsoleCapture };
+
+function validateConfiguration(configuration: CrumbConfiguration): void {
+  if (!configuration.projectKey?.trim()) {
+    throw new TypeError('Crumb projectKey must not be empty.');
+  }
+  if (!configuration.environment?.trim()) {
+    throw new TypeError('Crumb environment must not be empty.');
+  }
+
+  assertPositiveInteger(
+    configuration.capture?.maximumScreenshotDimension,
+    'capture.maximumScreenshotDimension'
+  );
+  assertPositiveInteger(
+    configuration.capture?.maximumScreenshotBytes,
+    'capture.maximumScreenshotBytes'
+  );
+  assertPositiveInteger(
+    configuration.diagnostics?.timeoutMs,
+    'diagnostics.timeoutMs'
+  );
+  assertPositiveInteger(
+    configuration.diagnostics?.logs?.lookbackMs,
+    'diagnostics.logs.lookbackMs'
+  );
+  assertPositiveInteger(
+    configuration.diagnostics?.logs?.maximumEntries,
+    'diagnostics.logs.maximumEntries'
+  );
+  assertPositiveInteger(
+    configuration.diagnostics?.logs?.maximumBytes,
+    'diagnostics.logs.maximumBytes'
+  );
+}
+
+function assertPositiveInteger(value: number | undefined, field: string): void {
+  if (value === undefined) return;
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`Crumb ${field} must be a positive integer.`);
+  }
+}
+
+const Crumb = Object.freeze({
+  start,
+  installReporter,
+  show,
+  log,
+  clearLogs,
+  enableConsoleCapture,
+  disableConsoleCapture,
+});
+
+export default Crumb;

package/src/log-buffer.ts

@@ -0,0 +1,265 @@
+import NativeCrumbReactNative from './NativeCrumbReactNative';
+import type {
+  CrumbLogEntry,
+  CrumbLogLevel,
+  CrumbLogMetadata,
+  CrumbLogOptions,
+} from './types';
+
+const DEFAULT_LOOKBACK_MS = 60_000;
+const DEFAULT_MAXIMUM_ENTRIES = 200;
+const DEFAULT_MAXIMUM_BYTES = 65_536;
+const MAXIMUM_METADATA_DEPTH = 4;
+const MAXIMUM_OBJECT_KEYS = 24;
+const MAXIMUM_ARRAY_ITEMS = 24;
+const MAXIMUM_STRING_LENGTH = 2_048;
+const MAXIMUM_ENTRY_BYTES = 16_384;
+
+interface BufferLimits {
+  lookbackMs: number;
+  maximumEntries: number;
+  maximumBytes: number;
+}
+
+type ConsoleMethod = (...data: unknown[]) => void;
+
+let limits: BufferLimits = {
+  lookbackMs: DEFAULT_LOOKBACK_MS,
+  maximumEntries: DEFAULT_MAXIMUM_ENTRIES,
+  maximumBytes: DEFAULT_MAXIMUM_BYTES,
+};
+let entries: CrumbLogEntry[] = [];
+let usedBytes = 0;
+let nativeStarted = false;
+let originalWarn: ConsoleMethod | undefined;
+let originalError: ConsoleMethod | undefined;
+let capturedWarn: ConsoleMethod | undefined;
+let capturedError: ConsoleMethod | undefined;
+
+export function configureLogBuffer(options: CrumbLogOptions | undefined): void {
+  limits = {
+    lookbackMs: options?.lookbackMs ?? DEFAULT_LOOKBACK_MS,
+    maximumEntries: options?.maximumEntries ?? DEFAULT_MAXIMUM_ENTRIES,
+    maximumBytes: options?.maximumBytes ?? DEFAULT_MAXIMUM_BYTES,
+  };
+  prune(Date.now());
+}
+
+export function markNativeStarted(): void {
+  nativeStarted = true;
+  NativeCrumbReactNative.clearLogs();
+  for (const entry of entries) {
+    NativeCrumbReactNative.addLog(JSON.stringify(entry));
+  }
+}
+
+export function clearLogs(): void {
+  entries = [];
+  usedBytes = 0;
+  if (nativeStarted) {
+    NativeCrumbReactNative.clearLogs();
+  }
+}
+
+export function writeLog(
+  level: CrumbLogLevel,
+  message: string,
+  metadata?: CrumbLogMetadata,
+  category: CrumbLogEntry['category'] = 'javascript'
+): void {
+  const timestampMs = Date.now();
+  const metadataText = metadata ? serializeMetadata(metadata) : undefined;
+  const entry: CrumbLogEntry = {
+    timestampMs,
+    level,
+    source: 'react-native',
+    category,
+    message: truncateUtf8(
+      metadataText ? `${message}\nmetadata=${metadataText}` : message,
+      MAXIMUM_ENTRY_BYTES
+    ),
+  };
+
+  const bytes = byteLength(JSON.stringify(entry));
+  entries.push(entry);
+  usedBytes += bytes;
+  prune(timestampMs);
+
+  if (nativeStarted && entries.includes(entry)) {
+    NativeCrumbReactNative.addLog(JSON.stringify(entry));
+  }
+}
+
+export function enableConsoleCapture(): void {
+  if (capturedWarn || capturedError) return;
+
+  originalWarn = console.warn;
+  originalError = console.error;
+  capturedWarn = (...data: unknown[]) => {
+    originalWarn?.apply(console, data);
+    writeConsoleLog('warning', data);
+  };
+  capturedError = (...data: unknown[]) => {
+    originalError?.apply(console, data);
+    writeConsoleLog('error', data);
+  };
+  console.warn = capturedWarn;
+  console.error = capturedError;
+}
+
+export function disableConsoleCapture(): void {
+  if (capturedWarn && console.warn === capturedWarn && originalWarn) {
+    console.warn = originalWarn;
+  }
+  if (capturedError && console.error === capturedError && originalError) {
+    console.error = originalError;
+  }
+  originalWarn = undefined;
+  originalError = undefined;
+  capturedWarn = undefined;
+  capturedError = undefined;
+}
+
+function writeConsoleLog(level: 'warning' | 'error', data: unknown[]): void {
+  const suppliedError = data.find(
+    (value): value is Error => value instanceof Error
+  );
+  const rendered = data.map(renderConsoleValue).join(' ');
+  const stack = suppliedError?.stack ?? new Error(`console.${level}`).stack;
+  const message = stack ? `${rendered}\n${stack}` : rendered;
+  writeLog(level, message, undefined, 'console');
+}
+
+function renderConsoleValue(value: unknown): string {
+  if (value instanceof Error) return value.stack ?? value.message;
+  if (typeof value === 'string') return value;
+  if (
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    typeof value === 'bigint'
+  ) {
+    return String(value);
+  }
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  return serializeMetadata({ value });
+}
+
+function serializeMetadata(metadata: CrumbLogMetadata): string {
+  const seen = new WeakSet<object>();
+  const bounded = boundValue(metadata, 0, seen);
+  try {
+    return truncateUtf8(JSON.stringify(bounded), MAXIMUM_ENTRY_BYTES / 2);
+  } catch {
+    return '"[Unserializable metadata]"';
+  }
+}
+
+function boundValue(
+  value: unknown,
+  depth: number,
+  seen: WeakSet<object>
+): unknown {
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: truncateString(value.message),
+      stack: value.stack ? truncateString(value.stack) : undefined,
+    };
+  }
+  if (typeof value === 'string') return truncateString(value);
+  if (
+    value === null ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  if (typeof value === 'bigint') return String(value);
+  if (typeof value === 'undefined') return '[Undefined]';
+  if (typeof value === 'function') return '[Function]';
+  if (typeof value === 'symbol') return String(value);
+  if (depth >= MAXIMUM_METADATA_DEPTH) return '[Max depth]';
+  if (typeof value !== 'object') return String(value);
+  if (seen.has(value)) return '[Circular]';
+
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = value
+      .slice(0, MAXIMUM_ARRAY_ITEMS)
+      .map((item) => boundValue(item, depth + 1, seen));
+    seen.delete(value);
+    return result;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(value).slice(0, MAXIMUM_OBJECT_KEYS)) {
+    result[truncateString(key)] = boundValue(
+      (value as Record<string, unknown>)[key],
+      depth + 1,
+      seen
+    );
+  }
+  seen.delete(value);
+  return result;
+}
+
+function prune(now: number): void {
+  const earliest = now - limits.lookbackMs;
+  while (entries[0] && entries[0].timestampMs < earliest) {
+    removeOldest();
+  }
+  while (
+    entries.length > limits.maximumEntries ||
+    usedBytes > limits.maximumBytes
+  ) {
+    removeOldest();
+  }
+}
+
+function removeOldest(): void {
+  const removed = entries.shift();
+  if (!removed) return;
+  usedBytes -= byteLength(JSON.stringify(removed));
+}
+
+function truncateString(value: string): string {
+  return value.length <= MAXIMUM_STRING_LENGTH
+    ? value
+    : `${value.slice(0, MAXIMUM_STRING_LENGTH)}…`;
+}
+
+function truncateUtf8(value: string, maximumBytes: number): string {
+  if (byteLength(value) <= maximumBytes) return value;
+
+  let low = 0;
+  let high = value.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (byteLength(value.slice(0, middle)) <= maximumBytes - 3) {
+      low = middle;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return `${value.slice(0, low)}…`;
+}
+
+function byteLength(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x7f) {
+      bytes += 1;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) index += 1;
+      bytes += 4;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+export type CrumbInvocation = 'shake' | 'programmatic';
+
+export type CrumbLogLevel =
+  | 'debug'
+  | 'info'
+  | 'notice'
+  | 'warning'
+  | 'error'
+  | 'fault';
+
+export interface CrumbRelease {
+  /** Defaults to the native bundle version name. */
+  appVersion?: string;
+  /** Defaults to the native bundle build number. */
+  nativeBuild?: string;
+  /** OTA or JavaScript bundle identity supplied by the host app. */
+  bundleVersion?: string;
+}
+
+export interface CrumbCaptureOptions {
+  screenshot?: boolean;
+  maximumScreenshotDimension?: number;
+  maximumScreenshotBytes?: number;
+}
+
+export interface CrumbLogOptions {
+  enabled?: boolean;
+  lookbackMs?: number;
+  maximumEntries?: number;
+  maximumBytes?: number;
+  /** Captures console.warn and console.error while preserving their behavior. */
+  captureConsole?: boolean;
+}
+
+export interface CrumbDiagnosticsOptions {
+  healthCheckUrl?: string;
+  timeoutMs?: number;
+  logs?: CrumbLogOptions;
+}
+
+export interface CrumbPrivacyOptions {
+  maskAllTextInputs?: boolean;
+  maskScreenshotsBeforeUpload?: boolean;
+}
+
+export interface CrumbUploadOptions {
+  /** Base URL of the Crumb ingestion API. Omit to keep reports local-only. */
+  ingestionUrl?: string;
+}
+
+export interface CrumbConfiguration {
+  projectKey: string;
+  environment: string;
+  release?: CrumbRelease;
+  invocation?: readonly CrumbInvocation[];
+  capture?: CrumbCaptureOptions;
+  diagnostics?: CrumbDiagnosticsOptions;
+  privacy?: CrumbPrivacyOptions;
+  upload?: CrumbUploadOptions;
+}
+
+export type CrumbLogMetadata = Readonly<Record<string, unknown>>;
+
+export interface CrumbLogEntry {
+  timestampMs: number;
+  level: CrumbLogLevel;
+  source: 'react-native';
+  category: 'javascript' | 'console';
+  message: string;
+}