react-native-bug-reporter 1.0.0

package/src/native/ScreenshotDetector.ts

@@ -0,0 +1,87 @@
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import type { ScreenshotData } from '../types';
+import { logger } from '../utils/logger';
+
+const LINKING_ERROR =
+  `The native module 'RNBugReporterScreenshot' from 'react-native-bug-reporter' is not linked.\n` +
+  Platform.select({
+    ios: '- Run `cd ios && pod install`, then rebuild the app.\n',
+    android: '- Rebuild the Android app (autolinking registers the module automatically).\n',
+    default: '',
+  }) +
+  '- A native rebuild is required after install — Fast Refresh is not enough.\n';
+
+const NativeScreenshot = NativeModules.RNBugReporterScreenshot as
+  | {
+      start: () => void;
+      stop: () => void;
+      addListener?: (event: string) => void;
+      removeListeners?: (count: number) => void;
+    }
+  | undefined;
+
+export type ScreenshotListener = (screenshot: ScreenshotData) => void;
+
+/**
+ * Thin wrapper around the native screenshot detector. Exposes a single
+ * `subscribe` method that starts detection and returns an unsubscribe fn.
+ */
+class ScreenshotDetector {
+  private emitter: NativeEventEmitter | null = null;
+  private listenerCount = 0;
+
+  isAvailable(): boolean {
+    return !!NativeScreenshot;
+  }
+
+  subscribe(listener: ScreenshotListener): () => void {
+    if (!NativeScreenshot) {
+      logger.warn(LINKING_ERROR);
+      return () => {};
+    }
+
+    if (!this.emitter) {
+      this.emitter = new NativeEventEmitter(NativeScreenshot as any);
+    }
+
+    const subscription = this.emitter.addListener(
+      'BugReporterScreenshotTaken',
+      (payload: { uri?: string | null; width?: number; height?: number }) => {
+        if (!payload || !payload.uri) {
+          // Detection fired but capture failed — still notify with no image so
+          // the user can file a report manually.
+          listener({ uri: '', width: 0, height: 0 });
+          return;
+        }
+        listener({
+          uri: payload.uri,
+          width: payload.width,
+          height: payload.height,
+        });
+      },
+    );
+
+    if (this.listenerCount === 0) {
+      try {
+        NativeScreenshot.start();
+      } catch (e) {
+        logger.warn('failed to start native detector', e);
+      }
+    }
+    this.listenerCount += 1;
+
+    return () => {
+      subscription.remove();
+      this.listenerCount = Math.max(0, this.listenerCount - 1);
+      if (this.listenerCount === 0) {
+        try {
+          NativeScreenshot.stop();
+        } catch (e) {
+          logger.warn('failed to stop native detector', e);
+        }
+      }
+    };
+  }
+}
+
+export const screenshotDetector = new ScreenshotDetector();

package/src/navigation/screenTracker.ts

@@ -0,0 +1,40 @@
+/**
+ * Lightweight current-screen tracker.
+ *
+ * The SDK is navigation-library agnostic. The host app reports its active
+ * route name here, and the SDK reads it when collecting context.
+ *
+ * Usage with React Navigation:
+ *
+ *   <NavigationContainer
+ *     onStateChange={(state) => {
+ *       const route = getActiveRouteName(state);
+ *       if (route) setCurrentScreen(route);
+ *     }}
+ *   />
+ *
+ * Or call `setCurrentScreen('Home')` manually from any screen's effect.
+ */
+let currentScreen: string | null = null;
+
+export function setCurrentScreen(name: string | null): void {
+  currentScreen = name;
+}
+
+export function getCurrentScreen(): string | null {
+  return currentScreen;
+}
+
+/**
+ * Walks a React Navigation state object to find the deepest active route name.
+ */
+export function getActiveRouteName(state: any): string | null {
+  if (!state || typeof state.index !== 'number' || !Array.isArray(state.routes)) {
+    return null;
+  }
+  const route = state.routes[state.index];
+  if (route?.state) {
+    return getActiveRouteName(route.state);
+  }
+  return route?.name ?? null;
+}

package/src/services/bugReportService.ts

@@ -0,0 +1,81 @@
+import type {
+  BugReport,
+  BugReportInput,
+  BugReporterConfig,
+  CollectedContext,
+  ScreenshotData,
+  SubmitState,
+} from '../types';
+import { insertReport, targetFromConfig, uploadScreenshot } from './supabaseService';
+import { logger } from '../utils/logger';
+
+export interface SubmitArgs {
+  input: BugReportInput;
+  context: CollectedContext;
+  screenshot: ScreenshotData | null;
+  config: BugReporterConfig;
+  onState?: (state: SubmitState) => void;
+}
+
+/**
+ * End-to-end submission pipeline (Supabase):
+ *   1. upload the screenshot to Supabase Storage (if present)
+ *   2. insert the report row into Postgres
+ *
+ * A Database Webhook → Edge Function then sends the notification email.
+ */
+export async function submitBugReport({
+  input,
+  context,
+  screenshot,
+  config,
+  onState,
+}: SubmitArgs): Promise<BugReport> {
+  const target = targetFromConfig(config);
+
+  // Normalize configured recipient(s).
+  const notifyEmails = (
+    Array.isArray(config.notifyEmails)
+      ? config.notifyEmails
+      : config.notifyEmails
+        ? [config.notifyEmails]
+        : []
+  )
+    .map(e => e.trim())
+    .filter(Boolean);
+
+  let screenshotUrl: string | null = null;
+  let screenshotPath: string | null = null;
+
+  try {
+    if (screenshot?.uri) {
+      onState?.('uploading');
+      const result = await uploadScreenshot(target, screenshot.uri);
+      screenshotUrl = result.publicUrl;
+      screenshotPath = result.storagePath;
+    }
+
+    onState?.('saving');
+    const report: Omit<BugReport, 'id'> = {
+      title: input.title.trim(),
+      description: input.description.trim(),
+      severity: input.severity,
+      screenshotUrl,
+      screenshotPath,
+      context,
+      status: 'open',
+      createdAt: context.timestamp,
+      ...(notifyEmails.length ? { notifyEmails } : {}),
+    };
+
+    const saved = await insertReport(target, report);
+    onState?.('done');
+    config.onSubmitted?.(saved);
+    return saved;
+  } catch (error) {
+    logger.error('submit failed', error);
+    onState?.('error');
+    config.onError?.(error);
+    throw error;
+  }
+}

package/src/services/supabaseService.ts

@@ -0,0 +1,195 @@
+import 'react-native-url-polyfill/auto';
+import { createClient, type SupabaseClient } from '@supabase/supabase-js';
+import type { BugReport } from '../types';
+import { logger } from '../utils/logger';
+
+/**
+ * Supabase backend for the SDK.
+ *
+ * - Screenshots upload to a Supabase Storage bucket.
+ * - Reports are inserted into a Postgres table.
+ * - A Database Webhook → Edge Function (see supabase/) emails each new report.
+ *
+ * The client is pure JS — no native config files. You only need the project URL
+ * and anon key (passed via BugReporterConfig).
+ */
+
+let client: SupabaseClient | null = null;
+let clientKey = '';
+
+function getClient(url: string, anonKey: string): SupabaseClient {
+  const key = `${url}::${anonKey}`;
+  if (!client || clientKey !== key) {
+    client = createClient(url, anonKey, {
+      auth: { persistSession: false, autoRefreshToken: false },
+    });
+    clientKey = key;
+  }
+  return client;
+}
+
+export interface SupabaseTarget {
+  supabaseUrl: string;
+  supabaseAnonKey: string;
+  tableName: string;
+  storageBucket: string;
+}
+
+/** DB row (snake_case) → SDK BugReport (camelCase). */
+function mapRow(row: Record<string, unknown>): BugReport {
+  return {
+    id: row.id as string,
+    title: (row.title as string) ?? '',
+    description: (row.description as string) ?? '',
+    severity: (row.severity as BugReport['severity']) ?? 'medium',
+    screenshotUrl: (row.screenshot_url as string) ?? null,
+    screenshotPath: (row.screenshot_path as string) ?? null,
+    context: (row.context as BugReport['context']) ?? ({} as BugReport['context']),
+    status: (row.status as BugReport['status']) ?? 'open',
+    createdAt: (row.created_at as string) ?? '',
+    notifyEmails: (row.notify_emails as string[]) ?? undefined,
+  };
+}
+
+export interface UploadResult {
+  publicUrl: string;
+  storagePath: string;
+}
+
+/**
+ * Uploads a local screenshot file to Supabase Storage; returns its public URL.
+ *
+ * Uses a multipart FormData POST to the Storage REST endpoint. React Native's
+ * networking streams `file://` / `content://` uris natively this way, which is
+ * reliable on real devices — unlike `fetch(fileUri).arrayBuffer()`, which throws
+ * "Network request failed" on Android.
+ */
+export async function uploadScreenshot(
+  target: SupabaseTarget,
+  localUri: string,
+): Promise<UploadResult> {
+  const storagePath = `${Date.now()}_${Math.floor(Math.random() * 1e6)}.png`;
+  const endpoint = `${target.supabaseUrl.replace(/\/+$/, '')}/storage/v1/object/${target.storageBucket}/${storagePath}`;
+
+  const form = new FormData();
+  form.append('file', {
+    uri: localUri,
+    name: storagePath,
+    type: 'image/png',
+  } as unknown as Blob);
+
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      apikey: target.supabaseAnonKey,
+      Authorization: `Bearer ${target.supabaseAnonKey}`,
+      'x-upsert': 'true',
+    },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Storage upload failed (${res.status}): ${text}`);
+  }
+
+  const publicUrl = `${target.supabaseUrl.replace(/\/+$/, '')}/storage/v1/object/public/${target.storageBucket}/${storagePath}`;
+  logger.log('screenshot uploaded', storagePath);
+  return { publicUrl, storagePath };
+}
+
+/** Inserts a bug report row and returns the saved report. */
+export async function insertReport(
+  target: SupabaseTarget,
+  report: Omit<BugReport, 'id'>,
+): Promise<BugReport> {
+  const supabase = getClient(target.supabaseUrl, target.supabaseAnonKey);
+  const { data, error } = await supabase
+    .from(target.tableName)
+    .insert({
+      title: report.title,
+      description: report.description,
+      severity: report.severity,
+      screenshot_url: report.screenshotUrl,
+      screenshot_path: report.screenshotPath,
+      context: report.context,
+      status: report.status,
+      created_at: report.createdAt,
+      notify_emails: report.notifyEmails ?? null,
+    })
+    .select()
+    .single();
+  if (error) throw error;
+  logger.log('report inserted', data.id);
+  return mapRow(data);
+}
+
+/**
+ * Subscribes to the reports table (newest first). Does an initial fetch, then
+ * refetches on any realtime change. Returns an unsubscribe function.
+ */
+export function subscribeToReports(
+  target: SupabaseTarget,
+  onData: (reports: BugReport[]) => void,
+  onError?: (error: Error) => void,
+): () => void {
+  const supabase = getClient(target.supabaseUrl, target.supabaseAnonKey);
+
+  const fetchAll = async () => {
+    const { data, error } = await supabase
+      .from(target.tableName)
+      .select('*')
+      .order('created_at', { ascending: false })
+      .limit(200);
+    if (error) {
+      logger.error('reports fetch error', error);
+      onError?.(error as unknown as Error);
+      return;
+    }
+    onData((data ?? []).map(mapRow));
+  };
+
+  fetchAll();
+
+  const channel = supabase
+    .channel(`bugreporter:${target.tableName}`)
+    .on(
+      'postgres_changes',
+      { event: '*', schema: 'public', table: target.tableName },
+      () => fetchAll(),
+    )
+    .subscribe();
+
+  return () => {
+    supabase.removeChannel(channel);
+  };
+}
+
+/** Updates a report's status (admin). */
+export async function updateReportStatus(
+  target: SupabaseTarget,
+  reportId: string,
+  status: BugReport['status'],
+): Promise<void> {
+  const supabase = getClient(target.supabaseUrl, target.supabaseAnonKey);
+  const { error } = await supabase
+    .from(target.tableName)
+    .update({ status })
+    .eq('id', reportId);
+  if (error) throw error;
+}
+
+/** Builds a SupabaseTarget from the SDK config (with defaults). */
+export function targetFromConfig(config: {
+  supabaseUrl: string;
+  supabaseAnonKey: string;
+  tableName?: string;
+  storageBucket?: string;
+}): SupabaseTarget {
+  return {
+    supabaseUrl: config.supabaseUrl,
+    supabaseAnonKey: config.supabaseAnonKey,
+    tableName: config.tableName ?? 'bug_reports',
+    storageBucket: config.storageBucket ?? 'bug-reports',
+  };
+}

package/src/theme.ts

@@ -0,0 +1,23 @@
+import type { BugReporterTheme } from './types';
+
+export interface ResolvedTheme extends Required<BugReporterTheme> {}
+
+export const defaultTheme: ResolvedTheme = {
+  primaryColor: '#2563eb',
+  backgroundColor: '#ffffff',
+  textColor: '#111827',
+  mutedColor: '#6b7280',
+  borderColor: '#e5e7eb',
+  errorColor: '#ef4444',
+};
+
+export function resolveTheme(theme?: BugReporterTheme): ResolvedTheme {
+  return { ...defaultTheme, ...(theme || {}) };
+}
+
+export const SEVERITY_COLORS: Record<string, string> = {
+  low: '#3b82f6',
+  medium: '#f59e0b',
+  high: '#ef4444',
+  critical: '#991b1b',
+};

package/src/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Core type definitions for the Universal Bug Reporter SDK.
+ */
+
+export type BugSeverity = 'low' | 'medium' | 'high' | 'critical';
+
+export const SEVERITIES: BugSeverity[] = ['low', 'medium', 'high', 'critical'];
+
+/**
+ * Information about the signed-in user, supplied by the host app.
+ * Everything is optional so the SDK works in apps without auth.
+ */
+export interface UserInfo {
+  id?: string | null;
+  name?: string | null;
+  email?: string | null;
+  /** Any extra attributes the host app wants to attach. */
+  [key: string]: unknown;
+}
+
+/** Device metadata collected automatically at report time. */
+export interface DeviceInfo {
+  brand: string;
+  manufacturer: string;
+  model: string;
+  deviceId: string;
+  systemName: string;
+  systemVersion: string;
+  isTablet: boolean;
+  isEmulator: boolean;
+  /** Unique, anonymous, install-scoped id. */
+  uniqueId: string;
+  totalMemory?: number;
+  usedMemory?: number;
+  batteryLevel?: number;
+  /** Free disk space in bytes. */
+  freeDisk?: number;
+}
+
+/** Host application metadata collected automatically. */
+export interface AppInfo {
+  appName: string;
+  bundleId: string;
+  version: string;
+  buildNumber: string;
+  /** Build channel/environment, e.g. "production". */
+  environment?: string;
+}
+
+/** Network connectivity snapshot. */
+export interface NetworkInfo {
+  isConnected: boolean | null;
+  isInternetReachable: boolean | null;
+  /** wifi | cellular | none | unknown | ... */
+  type: string;
+  /** Cellular generation when applicable, e.g. "4g". */
+  cellularGeneration?: string | null;
+}
+
+/** Everything the SDK auto-collects when a report is opened. */
+export interface CollectedContext {
+  user: UserInfo;
+  device: DeviceInfo;
+  app: AppInfo;
+  network: NetworkInfo;
+  currentScreen: string | null;
+  /** ISO-8601 timestamp. */
+  timestamp: string;
+}
+
+/** User-entered fields from the report modal. */
+export interface BugReportInput {
+  title: string;
+  description: string;
+  severity: BugSeverity;
+}
+
+/** The full bug report persisted on the backend. */
+export interface BugReport extends BugReportInput {
+  id?: string;
+  screenshotUrl: string | null;
+  screenshotPath: string | null;
+  context: CollectedContext;
+  status: 'open' | 'in_progress' | 'resolved' | 'closed';
+  createdAt: string;
+  /** Recipient address(es) for the notification email (from config). */
+  notifyEmails?: string[];
+}
+
+/** A screenshot captured / detected on device. */
+export interface ScreenshotData {
+  /** Local file URI (file:// or content:// or ph://). */
+  uri: string;
+  /** Optional base64 payload when a uri is unavailable. */
+  base64?: string | null;
+  width?: number;
+  height?: number;
+}
+
+export type SubmitState = 'idle' | 'collecting' | 'uploading' | 'saving' | 'done' | 'error';
+
+/** Theme overrides for the modal UI. */
+export interface BugReporterTheme {
+  primaryColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  mutedColor?: string;
+  borderColor?: string;
+  errorColor?: string;
+}
+
+/** Configuration passed to BugReporterProvider. */
+export interface BugReporterConfig {
+  /** Supabase project URL, e.g. "https://xxxx.supabase.co". */
+  supabaseUrl: string;
+  /** Supabase anon (public) API key. */
+  supabaseAnonKey: string;
+  /** Postgres table reports are inserted into. Defaults to "bug_reports". */
+  tableName?: string;
+  /** Supabase Storage bucket for screenshots. Defaults to "bug-reports". */
+  storageBucket?: string;
+  /**
+   * Returns the current signed-in user. Called lazily each time a report
+   * is opened, so it always reflects the latest auth state.
+   */
+  getUser?: () => UserInfo | Promise<UserInfo>;
+  /**
+   * Returns the current screen/route name. Wire this to your navigation
+   * library (see `screenTracker`).
+   */
+  getCurrentScreen?: () => string | null;
+  /**
+   * Email address(es) the notification should be sent to. Stored on the report
+   * row; the Supabase Edge Function reads it and emails these recipients.
+   * Accepts a single address or an array.
+   */
+  notifyEmails?: string | string[];
+  /** Build channel/environment label attached to every report. */
+  environment?: string;
+  /** Disable automatic screenshot detection (manual trigger only). */
+  disableAutoDetect?: boolean;
+  /**
+   * Show the "Automatically attached" context summary (screen, user, app,
+   * device, network) inside the report modal. Defaults to true. Set false to
+   * hide it from the user — the data is still collected and sent to the backend.
+   */
+  showContextSummary?: boolean;
+  /** Theme overrides. */
+  theme?: BugReporterTheme;
+  /** Called after a report is successfully submitted. */
+  onSubmitted?: (report: BugReport) => void;
+  /** Called when submission fails. */
+  onError?: (error: unknown) => void;
+  /** Enable verbose console logging. */
+  debug?: boolean;
+}

package/src/utils/logger.ts

@@ -0,0 +1,24 @@
+/**
+ * Tiny namespaced logger that can be toggled via config.debug.
+ */
+let enabled = false;
+
+const PREFIX = '[BugReporter]';
+
+export const logger = {
+  setEnabled(value: boolean) {
+    enabled = value;
+  },
+  log(...args: unknown[]) {
+    if (enabled) {
+      console.log(PREFIX, ...args);
+    }
+  },
+  warn(...args: unknown[]) {
+    // Warnings always surface — they usually indicate a setup problem.
+    console.warn(PREFIX, ...args);
+  },
+  error(...args: unknown[]) {
+    console.error(PREFIX, ...args);
+  },
+};