react-native-prod-debugger 1.0.0

package/src/core/types.ts

@@ -0,0 +1,339 @@
+import { ReactNode } from 'react';
+
+// ─── Gesture Configuration ──────────────────────────────────────────────────
+
+/** Supported gesture types for activating the debugger overlay. */
+export type GestureType = 'threeFingerLongPress' | 'twoFingerTripleTap' | 'shake' | 'custom';
+
+// ─── Provider Configuration ─────────────────────────────────────────────────
+
+/** Configuration for the DebuggerProvider. */
+export interface DebuggerConfig {
+  /** Whether the debugger is enabled. Defaults to `true`. */
+  enabled?: boolean;
+
+  /** Gesture type to activate the overlay. Defaults to `'threeFingerLongPress'`. */
+  gesture?: GestureType;
+
+  /** Duration in ms for long press gestures. Defaults to `800`. */
+  longPressDuration?: number;
+
+  /** Number of fingers for multi-touch gestures. Defaults to `3`. */
+  numberOfFingers?: number;
+
+  /** Auto-start console interception on mount. Defaults to `true`. */
+  interceptConsole?: boolean;
+
+  /** Auto-start network interception on mount. Defaults to `true`. */
+  interceptNetwork?: boolean;
+
+  /** Auto-start crash capturing on mount. Defaults to `true`. */
+  interceptCrashes?: boolean;
+
+  /** Maximum number of network requests to keep in memory. Defaults to `500`. */
+  maxNetworkRequests?: number;
+
+  /** Maximum number of console entries to keep in memory. Defaults to `1000`. */
+  maxConsoleEntries?: number;
+
+  /** Maximum number of timeline events to keep in memory. Defaults to `2000`. */
+  maxTimelineEvents?: number;
+
+  /** Application version string shown in Device Info. */
+  appVersion?: string;
+
+  /** Application build number shown in Device Info. */
+  buildNumber?: string;
+
+  /** Bundle identifier shown in Device Info. */
+  bundleId?: string;
+
+  /** Custom theme overrides. */
+  theme?: Partial<DebuggerTheme>;
+
+  /** List of plugin IDs to disable. */
+  disabledPlugins?: string[];
+
+  /** Bubble initial position. */
+  bubblePosition?: { x: number; y: number };
+
+  /** Bubble size in dp. Defaults to `50`. */
+  bubbleSize?: number;
+}
+
+// ─── Theme ──────────────────────────────────────────────────────────────────
+
+export interface DebuggerTheme {
+  background: string;
+  surface: string;
+  surfaceAlt: string;
+  text: string;
+  textSecondary: string;
+  textMuted: string;
+  accent: string;
+  accentLight: string;
+  success: string;
+  warning: string;
+  error: string;
+  info: string;
+  border: string;
+  overlay: string;
+  bubbleBackground: string;
+  bubbleIcon: string;
+  codeBackground: string;
+  codeText: string;
+  headerBackground: string;
+  tabActive: string;
+  tabInactive: string;
+  statusBarOk: string;
+  statusBarWarn: string;
+  statusBarError: string;
+  shadow: string;
+}
+
+// ─── Plugin System ──────────────────────────────────────────────────────────
+
+/** Props passed to every plugin component. */
+export interface PluginComponentProps {
+  /** Current theme tokens. */
+  theme: DebuggerTheme;
+}
+
+/** Definition of a debugger plugin. */
+export interface DebuggerPlugin {
+  /** Unique plugin identifier. */
+  id: string;
+  /** Display name shown in the tab bar. */
+  name: string;
+  /** Emoji icon for the tab. */
+  icon: string;
+  /** React component rendered in the plugin's tab. */
+  component: React.ComponentType<PluginComponentProps>;
+  /** Called when the debugger mounts. Useful for starting interceptors. */
+  onInit?: () => void;
+  /** Called when the debugger unmounts. Useful for cleanup. */
+  onDestroy?: () => void;
+  /** Plugin sort order. Lower numbers appear first. Defaults to `100`. */
+  order?: number;
+}
+
+// ─── Network Inspector ──────────────────────────────────────────────────────
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | string;
+
+export interface NetworkRequest {
+  /** Unique request ID. */
+  id: string;
+  /** HTTP method. */
+  method: HttpMethod;
+  /** Full URL. */
+  url: string;
+  /** Request start time (UNIX ms). */
+  startTime: number;
+  /** Request end time (UNIX ms). */
+  endTime?: number;
+  /** Duration in ms. */
+  duration?: number;
+  /** HTTP status code. */
+  status?: number;
+  /** Request headers. */
+  requestHeaders?: Record<string, string>;
+  /** Response headers. */
+  responseHeaders?: Record<string, string>;
+  /** Request body (string or serialized). */
+  requestBody?: string;
+  /** Response body (string or serialized). */
+  responseBody?: string;
+  /** Content type of the response. */
+  responseContentType?: string;
+  /** Response size in bytes. */
+  responseSize?: number;
+  /** Request size in bytes. */
+  requestSize?: number;
+  /** Whether the request errored. */
+  isError?: boolean;
+  /** Error message if failed. */
+  errorMessage?: string;
+  /** GraphQL operation name if detected. */
+  gqlOperation?: string;
+  /** GraphQL operation type (query/mutation/subscription). */
+  gqlType?: string;
+}
+
+// ─── Console ────────────────────────────────────────────────────────────────
+
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+
+export interface ConsoleEntry {
+  /** Unique entry ID. */
+  id: string;
+  /** Log level. */
+  level: ConsoleLevel;
+  /** Timestamp (UNIX ms). */
+  timestamp: number;
+  /** Serialized arguments. */
+  message: string;
+  /** Raw arguments for inspection. */
+  args?: unknown[];
+}
+
+// ─── Feature Flags ──────────────────────────────────────────────────────────
+
+export type FlagType = 'boolean' | 'string' | 'number' | 'json';
+
+export interface FeatureFlag {
+  /** Unique flag key. */
+  key: string;
+  /** Display label. */
+  label?: string;
+  /** Data type. */
+  type: FlagType;
+  /** Default (original) value. */
+  defaultValue: boolean | string | number | object;
+  /** Current (possibly overridden) value. */
+  currentValue: boolean | string | number | object;
+  /** Description of the flag. */
+  description?: string;
+  /** Group/category for organization. */
+  group?: string;
+}
+
+// ─── Remote Config ──────────────────────────────────────────────────────────
+
+export interface RemoteConfigValue {
+  key: string;
+  value: string | number | boolean | object;
+  source: 'remote' | 'default' | 'static';
+}
+
+export interface RemoteConfigProvider {
+  /** Get all config key-value pairs. */
+  getAll: () => Promise<RemoteConfigValue[]> | RemoteConfigValue[];
+  /** Get a single value by key. */
+  getValue?: (key: string) => Promise<RemoteConfigValue | null> | RemoteConfigValue | null;
+  /** Last fetch timestamp. */
+  getLastFetchTime?: () => Promise<number | null> | number | null;
+  /** Provider name (e.g. "Firebase", "LaunchDarkly"). */
+  name?: string;
+}
+
+// ─── Storage ────────────────────────────────────────────────────────────────
+
+export interface StorageAdapter {
+  /** Adapter display name. */
+  name: string;
+  /** Get all keys. */
+  getAllKeys: () => Promise<string[]>;
+  /** Get a value by key. */
+  getItem: (key: string) => Promise<string | null>;
+  /** Set a value by key. */
+  setItem: (key: string, value: string) => Promise<void>;
+  /** Remove a key. */
+  removeItem: (key: string) => Promise<void>;
+  /** Clear all storage. */
+  clear?: () => Promise<void>;
+}
+
+// ─── Timeline ───────────────────────────────────────────────────────────────
+
+export type EventCategory =
+  | 'network'
+  | 'navigation'
+  | 'state'
+  | 'lifecycle'
+  | 'error'
+  | 'console'
+  | 'custom'
+  | string;
+
+export interface TimelineEvent {
+  /** Unique event ID. */
+  id: string;
+  /** Timestamp (UNIX ms). */
+  timestamp: number;
+  /** Event category for filtering. */
+  category: EventCategory;
+  /** Short event title. */
+  title: string;
+  /** Optional detailed data. */
+  data?: unknown;
+  /** Emoji icon. */
+  icon?: string;
+  /** Color hint for the UI. */
+  color?: string;
+}
+
+// ─── Crash Reporter ─────────────────────────────────────────────────────────
+
+export interface CrashEntry {
+  /** Unique entry ID. */
+  id: string;
+  /** Timestamp (UNIX ms). */
+  timestamp: number;
+  /** Error message. */
+  message: string;
+  /** Stack trace. */
+  stack?: string;
+  /** Whether it was fatal. */
+  isFatal: boolean;
+  /** Component stack (React error boundary). */
+  componentStack?: string;
+}
+
+// ─── Custom Actions ─────────────────────────────────────────────────────────
+
+export interface CustomAction {
+  /** Unique action ID. */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** Emoji icon. */
+  icon?: string;
+  /** Async handler executed when the action is triggered. */
+  handler: () => void | Promise<void>;
+  /** If true, shows a confirmation dialog before executing. */
+  destructive?: boolean;
+  /** Group/category for organization. */
+  group?: string;
+  /** Description shown under the action name. */
+  description?: string;
+}
+
+// ─── Navigation ─────────────────────────────────────────────────────────────
+
+export interface NavigationRoute {
+  name: string;
+  key: string;
+  params?: Record<string, unknown>;
+  state?: NavigationState;
+}
+
+export interface NavigationState {
+  index: number;
+  routes: NavigationRoute[];
+  type?: string;
+  stale?: boolean;
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+export interface DebuggerContextValue {
+  /** Whether the debugger is visible. */
+  isVisible: boolean;
+  /** Toggle overlay visibility. */
+  toggle: () => void;
+  /** Show the overlay. */
+  show: () => void;
+  /** Hide the overlay. */
+  hide: () => void;
+  /** Full config. */
+  config: Required<DebuggerConfig>;
+  /** Current theme. */
+  theme: DebuggerTheme;
+  /** Registered plugins. */
+  plugins: DebuggerPlugin[];
+}
+
+export interface ChildrenProp {
+  children: ReactNode;
+}

package/src/core/useDebugger.ts

@@ -0,0 +1,24 @@
+import { useContext } from 'react';
+import { DebuggerContext } from './DebuggerProvider';
+import type { DebuggerContextValue } from './types';
+
+/**
+ * Hook to access the debugger context.
+ *
+ * @example
+ * ```tsx
+ * const { show, hide, toggle, isVisible } = useDebugger();
+ *
+ * // Programmatically open the debugger
+ * show();
+ * ```
+ */
+export function useDebugger(): DebuggerContextValue {
+  const context = useContext(DebuggerContext);
+  if (!context) {
+    throw new Error(
+      '[react-native-prod-debugger] useDebugger must be used within a <DebuggerProvider>.',
+    );
+  }
+  return context;
+}

package/src/core/utils.ts

@@ -0,0 +1,221 @@
+import { Clipboard, Share, Platform } from 'react-native';
+
+/** Generate a unique ID (collision-safe for debugging purposes). */
+export function generateId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+
+/** Format bytes into a human-readable string. */
+export function formatBytes(bytes: number | undefined): string {
+  if (bytes === undefined || bytes === null) return '—';
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const value = bytes / Math.pow(1024, i);
+  return `${value.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+/** Format milliseconds into a readable duration. */
+export function formatDuration(ms: number | undefined): string {
+  if (ms === undefined || ms === null) return '—';
+  if (ms < 1) return '<1ms';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}
+
+/** Format a UNIX timestamp into a local time string (HH:MM:SS.mmm). */
+export function formatTimestamp(ts: number): string {
+  const d = new Date(ts);
+  const h = d.getHours().toString().padStart(2, '0');
+  const m = d.getMinutes().toString().padStart(2, '0');
+  const s = d.getSeconds().toString().padStart(2, '0');
+  const ms = d.getMilliseconds().toString().padStart(3, '0');
+  return `${h}:${m}:${s}.${ms}`;
+}
+
+/** Format a relative time ago (e.g., "2s ago", "5m ago"). */
+export function formatTimeAgo(ts: number): string {
+  const diff = Date.now() - ts;
+  if (diff < 1000) return 'just now';
+  if (diff < 60_000) return `${Math.floor(diff / 1000)}s ago`;
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`;
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`;
+  return `${Math.floor(diff / 86_400_000)}d ago`;
+}
+
+/** Truncate a string with ellipsis if it exceeds maxLength. */
+export function truncate(str: string, maxLength: number = 200): string {
+  if (!str) return '';
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + '…';
+}
+
+/** Safely serialize any value to a JSON string with pretty printing. */
+export function safeStringify(value: unknown, indent: number = 2): string {
+  try {
+    if (value === undefined) return 'undefined';
+    if (value === null) return 'null';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`;
+    if (value instanceof Error) {
+      return JSON.stringify(
+        { name: value.name, message: value.message, stack: value.stack },
+        null,
+        indent,
+      );
+    }
+    return JSON.stringify(value, getCircularReplacer(), indent);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Safely parse a JSON string, returning null on failure. */
+export function safeParse(str: string): unknown | null {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}
+
+/** Copy text to the device clipboard. */
+export async function copyToClipboard(text: string): Promise<void> {
+  try {
+    if (Clipboard?.setString) {
+      Clipboard.setString(text);
+    }
+  } catch {
+    // Silently fail — clipboard may not be available
+  }
+}
+
+/** Share text via the native share sheet. */
+export async function shareText(text: string, title?: string): Promise<void> {
+  try {
+    await Share.share(
+      { message: text, title },
+      Platform.OS === 'ios' ? { subject: title } : undefined,
+    );
+  } catch {
+    // Silently fail — share may be cancelled
+  }
+}
+
+/** Get the HTTP status color based on the status code. */
+export function getStatusColor(status: number | undefined): string {
+  if (!status) return '#6B6B80';
+  if (status < 300) return '#10B981'; // green
+  if (status < 400) return '#F59E0B'; // yellow
+  return '#EF4444'; // red
+}
+
+/** Get the HTTP method color. */
+export function getMethodColor(method: string): string {
+  const colors: Record<string, string> = {
+    GET: '#3B82F6',
+    POST: '#10B981',
+    PUT: '#F59E0B',
+    PATCH: '#A78BFA',
+    DELETE: '#EF4444',
+    HEAD: '#6B6B80',
+    OPTIONS: '#6B6B80',
+  };
+  return colors[method.toUpperCase()] || '#6B6B80';
+}
+
+/** Get a console level color. */
+export function getLevelColor(level: string): string {
+  const colors: Record<string, string> = {
+    log: '#EAEAEA',
+    info: '#3B82F6',
+    warn: '#F59E0B',
+    error: '#EF4444',
+    debug: '#A78BFA',
+  };
+  return colors[level] || '#EAEAEA';
+}
+
+/**
+ * Extract GraphQL operation name and type from request body.
+ * Returns `null` if it's not a GraphQL request.
+ */
+export function extractGraphQLInfo(
+  body: string | undefined,
+): { operation: string; type: string } | null {
+  if (!body) return null;
+  try {
+    const parsed = JSON.parse(body);
+    const query: string | undefined = parsed?.query;
+    if (!query) return null;
+
+    // Extract operation type and name
+    const match = query.match(/^\s*(query|mutation|subscription)\s+(\w+)/);
+    if (match) {
+      return { type: match[1], operation: match[2] };
+    }
+
+    // Try named operations without explicit type
+    const nameMatch = query.match(/^\s*\{\s*(\w+)/);
+    if (nameMatch) {
+      return { type: 'query', operation: nameMatch[1] };
+    }
+
+    return { type: 'query', operation: parsed.operationName || 'Unknown' };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convert a network request to a cURL command string.
+ */
+export function toCurl(request: {
+  method: string;
+  url: string;
+  requestHeaders?: Record<string, string>;
+  requestBody?: string;
+}): string {
+  const parts: string[] = [`curl -X ${request.method}`];
+
+  if (request.requestHeaders) {
+    for (const [key, value] of Object.entries(request.requestHeaders)) {
+      parts.push(`-H '${key}: ${value}'`);
+    }
+  }
+
+  if (request.requestBody) {
+    parts.push(`-d '${request.requestBody.replace(/'/g, "\\'")}'`);
+  }
+
+  parts.push(`'${request.url}'`);
+  return parts.join(' \\\n  ');
+}
+
+/** Debounce function calls. */
+export function debounce<T extends (...args: unknown[]) => void>(
+  fn: T,
+  delay: number,
+): (...args: Parameters<T>) => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return (...args: Parameters<T>) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), delay);
+  };
+}
+
+/**
+ * Circular reference replacer for JSON.stringify.
+ * Prevents "Converting circular structure to JSON" errors.
+ */
+function getCircularReplacer() {
+  const seen = new WeakSet();
+  return (_key: string, value: unknown) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) return '[Circular]';
+      seen.add(value);
+    }
+    return value;
+  };
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * react-native-prod-debugger
+ *
+ * A comprehensive, in-app debugging toolkit for React Native
+ * that works in production builds.
+ *
+ * @packageDocumentation
+ */
+
+// ─── Core ────────────────────────────────────────────────────────────────────
+export { DebuggerProvider } from './core/DebuggerProvider';
+export { useDebugger } from './core/useDebugger';
+export { PluginRegistry, registerPlugin, unregisterPlugin } from './core/PluginRegistry';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+export type {
+  DebuggerConfig,
+  DebuggerPlugin,
+  DebuggerTheme,
+  GestureType,
+  NetworkRequest,
+  ConsoleEntry,
+  ConsoleLevel,
+  FeatureFlag,
+  FlagType,
+  RemoteConfigProvider,
+  RemoteConfigValue,
+  StorageAdapter,
+  TimelineEvent,
+  EventCategory,
+  CrashEntry,
+  CustomAction,
+  PluginComponentProps,
+} from './core/types';
+
+// ─── Plugin APIs ─────────────────────────────────────────────────────────────
+
+// Network Inspector
+export { NetworkInterceptor } from './plugins/network/NetworkInterceptor';
+
+// Console Viewer
+export { ConsoleInterceptor } from './plugins/console/ConsoleInterceptor';
+
+// Feature Flags
+export { registerFlag, resetFlags, getFlag } from './plugins/featureFlags/flagStore';
+
+// State Inspector
+export { setStateAdapter, removeStateAdapter } from './plugins/stateInspector/stateAdapterRegistry';
+export type { StateAdapter } from './plugins/stateInspector/stateAdapterRegistry';
+
+// Remote Config
+export { setRemoteConfigProvider } from './plugins/remoteConfig/remoteConfigStore';
+
+// Storage Browser
+export {
+  setStorageAdapter,
+  removeStorageAdapter,
+} from './plugins/storageBrowser/storageAdapterRegistry';
+
+// Navigation Inspector
+export { setNavigationRef } from './plugins/navigationInspector/navigationStore';
+
+// Custom Actions
+export { registerAction, removeAction } from './plugins/customActions/actionStore';
+
+// Timeline / Event Logger
+export { logTimelineEvent } from './plugins/timeline/timelineStore';