react-native-bug-reporter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# react-native-bug-reporter
+
+> Universal bug reporting for any React Native app. Detect screenshots, annotate
+> them, collect device/app/user context, and ship reports to **Supabase**
+> (Postgres + Storage). A Database Webhook → Edge Function emails each report.
+
+When a user takes a screenshot anywhere in your app, a report modal pops up with
+the screenshot pre-attached. The user can **mark the bug** (pen/arrow/point/text),
+adds a title/description/severity; the SDK auto-collects **user, device, app,
+current screen, network, timestamp** and writes everything to Supabase.
+
+- 📸 Automatic screenshot detection (native iOS + Android)
+- ✏️ Built-in screenshot annotation editor (pen, arrow, point, text)
+- 🧩 One-component install — `<BugReporterProvider>`
+- 🔍 Auto-collected context (device, app, user, screen, network, time)
+- 🟢 Supabase backend (Postgres + Storage + Edge Function email) — just URL + anon key
+- 🛠 Built-in in-app admin viewer (live realtime)
+- 🎨 Themeable, TypeScript-first, autolinked
+
+---
+
+## 1. Install
+
+```sh
+npm install react-native-bug-reporter \
+  @supabase/supabase-js react-native-url-polyfill \
+  @react-native-community/netinfo react-native-device-info \
+  react-native-svg react-native-view-shot
+cd ios && pod install && cd ..
+```
+
+The native modules (screenshot detection, svg, view-shot, device-info, netinfo)
+need a **native rebuild** after installing. The Supabase client itself is pure
+JS — no native config files, no `google-services.json`.
+
+---
+
+## 2. Set up Supabase
+
+Run [`supabase/schema.sql`](../supabase/schema.sql) in your project's SQL editor
+(creates the `bug_reports` table + RLS + the public `bug-reports` storage
+bucket), then deploy the email Edge Function:
+
+```sh
+supabase functions deploy send-bug-email --no-verify-jwt
+supabase secrets set SMTP_HOST=smtp.gmail.com SMTP_PORT=465 SMTP_SECURE=true \
+  SMTP_USER=you@gmail.com SMTP_PASS=<app-password> NOTIFY_EMAIL_TO=admin@you.com
+```
+
+Add a **Database Webhook** (Insert on `bug_reports`) → the `send-bug-email`
+function. Full steps: [`supabase/README.md`](../supabase/README.md).
+
+---
+
+## 3. Wrap your app
+
+```tsx
+import { BugReporterProvider } from 'react-native-bug-reporter';
+
+export default function App() {
+  return (
+    <BugReporterProvider
+      config={{
+        supabaseUrl: 'https://YOURPROJECT.supabase.co',
+        supabaseAnonKey: 'eyJ...anon-key',          // safe to ship; RLS controls access
+        notifyEmails: 'admin@yourcompany.com',      // who gets the email
+        environment: __DEV__ ? 'development' : 'production',
+        getUser: () => ({ id: user.id, name: user.name, email: user.email }),
+      }}
+    >
+      <RootNavigator />
+    </BugReporterProvider>
+  );
+}
+```
+
+**Now take a screenshot in the running app — the report modal appears with the
+screenshot attached.** 🎉
+
+---
+
+## 4. Full functionality
+
+### Trigger the modal manually
+
+```tsx
+import { useBugReporter } from 'react-native-bug-reporter';
+
+function HelpScreen() {
+  const { openReporter } = useBugReporter();
+  return <Button title="Report a bug" onPress={() => openReporter()} />;
+}
+```
+
+`useBugReporter()` returns:
+
+| Field                 | Type                                    | Description |
+|-----------------------|-----------------------------------------|-------------|
+| `openReporter`        | `(screenshot?) => void`                 | Open the modal (optionally pre-attach an image). |
+| `closeReporter`       | `() => void`                            | Close it. |
+| `isOpen`              | `boolean`                               | Modal visibility. |
+| `isAutoDetectEnabled` | `boolean`                               | Whether screenshot detection is on. |
+
+### Track the current screen
+
+The SDK is navigation-agnostic. Report the active route so it's attached to bug
+reports. With **React Navigation**:
+
+```tsx
+import { setCurrentScreen, getActiveRouteName } from 'react-native-bug-reporter';
+
+<NavigationContainer
+  onStateChange={(state) => {
+    const route = getActiveRouteName(state);
+    if (route) setCurrentScreen(route);
+  }}
+/>
+```
+
+…then pass `getCurrentScreen` in the config:
+
+```tsx
+import { getCurrentScreen } from 'react-native-bug-reporter';
+// config: { ..., getCurrentScreen }
+```
+
+Or just call `setCurrentScreen('Checkout')` from any screen's effect.
+
+### Admin viewer (in-app)
+
+```tsx
+import { BugReportAdminScreen } from 'react-native-bug-reporter';
+
+<BugReportAdminScreen config={{ supabaseUrl, supabaseAnonKey }} />
+```
+
+Live-lists all reports from Supabase (realtime) with screenshot thumbnails and a
+tap-to-cycle status control. Pass the same `supabaseUrl` + `supabaseAnonKey`.
+
+### Theming
+
+```tsx
+config={{
+  collectionName: 'bug_reports',
+  theme: {
+    primaryColor: '#7c3aed',
+    backgroundColor: '#ffffff',
+    textColor: '#111827',
+    mutedColor: '#6b7280',
+    borderColor: '#e5e7eb',
+    errorColor: '#ef4444',
+  },
+}}
+```
+
+### Callbacks & options
+
+```tsx
+config={{
+  collectionName: 'bug_reports',
+  disableAutoDetect: false,          // set true for manual-only reporting
+  debug: __DEV__,                    // verbose logging
+  onSubmitted: (report) => analytics.track('bug_reported', { id: report.id }),
+  onError: (err) => console.warn(err),
+}}
+```
+
+---
+
+## Config reference (`BugReporterConfig`)
+
+| Option              | Type                            | Default        | Description |
+|---------------------|---------------------------------|----------------|-------------|
+| `supabaseUrl`       | `string` **(required)**         | —              | Supabase project URL. |
+| `supabaseAnonKey`   | `string` **(required)**         | —              | Supabase anon (public) key. |
+| `tableName`         | `string`                        | `bug_reports`  | Postgres table for reports. |
+| `storageBucket`     | `string`                        | `bug-reports`  | Storage bucket for screenshots. |
+| `notifyEmails`      | `string \| string[]`            | —              | Recipient(s) for the email (stored on the row; Edge Function reads it). |
+| `getUser`           | `() => UserInfo \| Promise<…>`  | —              | Current signed-in user. |
+| `getCurrentScreen`  | `() => string \| null`          | —              | Active route name. |
+| `environment`       | `string`                        | —              | e.g. `"production"`. |
+| `showContextSummary`| `boolean`                       | `true`         | Show the "Automatically attached" block (data is always collected). |
+| `disableAutoDetect` | `boolean`                       | `false`        | Manual-only reporting. |
+| `theme`             | `BugReporterTheme`              | light theme    | Color overrides. |
+| `onSubmitted`       | `(report) => void`              | —              | Success callback. |
+| `onError`           | `(error) => void`               | —              | Failure callback. |
+| `debug`             | `boolean`                       | `false`        | Verbose logging. |
+
+---
+
+## How screenshot capture works
+
+Instead of reading the device Photos library (permission-heavy, may miss the
+frame), the native modules **snapshot the current app window** the instant a
+screenshot is detected:
+
+- **iOS** — `userDidTakeScreenshotNotification` → render the key window → PNG.
+- **Android 14+** — `Activity.registerScreenCaptureCallback` → `PixelCopy` → PNG.
+- **Android ≤13** — `MediaStore` `ContentObserver` → `PixelCopy` → PNG.
+
+The JS layer shows the image in the modal and streams it to your backend as
+`multipart/form-data`.
+
+---
+
+## Publishing your own copy
+
+```sh
+npm version patch
+npm publish        # runs `bob build` via the prepare script
+```
+
+The build emits CommonJS, ESM, and TypeScript declarations to `lib/`.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,49 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.1.1"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '1.9.24')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+android {
+  namespace "com.bugreporter"
+  compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 24)
+    targetSdkVersion safeExtGet('targetSdkVersion', 35)
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  // Resolved against the host app's React Native version.
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,11 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!-- Official screenshot detection on Android 14+ (no runtime prompt). -->
+  <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
+
+  <!-- MediaStore fallback for screenshot detection on Android 13 and below. -->
+  <uses-permission
+      android:name="android.permission.READ_MEDIA_IMAGES"
+      android:maxSdkVersion="33" />
+
+</manifest>

package/android/src/main/java/com/bugreporter/ScreenshotDetectorModule.kt

@@ -0,0 +1,227 @@
+package com.bugreporter
+
+import android.app.Activity
+import android.database.ContentObserver
+import android.graphics.Bitmap
+import android.net.Uri
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.provider.MediaStore
+import android.view.PixelCopy
+import android.view.View
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import java.io.File
+import java.io.FileOutputStream
+import java.util.concurrent.Executor
+
+/**
+ * Native screenshot detector for Android.
+ *
+ * Detection strategy:
+ *  - API 34+ (Android 14): the official `Activity.registerScreenCaptureCallback`,
+ *    which fires when the user takes a screenshot — no storage permission needed.
+ *  - API < 34: a `ContentObserver` on the MediaStore images table that fires when
+ *    a new image lands in a "Screenshots" path. Requires media read permission.
+ *
+ * On detection we snapshot the current Activity window (PixelCopy on API 26+,
+ * canvas draw otherwise) into a PNG in the cache dir and emit a
+ * `BugReporterScreenshotTaken` event with the file URI and dimensions.
+ */
+class ScreenshotDetectorModule(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private var contentObserver: ContentObserver? = null
+  private var screenCaptureCallback: Any? = null
+  private var isListening = false
+
+  override fun getName(): String = NAME
+
+  @ReactMethod
+  fun start() {
+    if (isListening) return
+    isListening = true
+    if (Build.VERSION.SDK_INT >= 34) {
+      registerScreenCaptureCallback()
+    } else {
+      registerContentObserver()
+    }
+  }
+
+  @ReactMethod
+  fun stop() {
+    isListening = false
+    contentObserver?.let {
+      reactContext.contentResolver.unregisterContentObserver(it)
+      contentObserver = null
+    }
+    if (Build.VERSION.SDK_INT >= 34) {
+      unregisterScreenCaptureCallback()
+    }
+  }
+
+  // Required for NativeEventEmitter on the JS side.
+  @ReactMethod
+  fun addListener(eventName: String) {}
+
+  @ReactMethod
+  fun removeListeners(count: Int) {}
+
+  // -- Android 14+ official callback ----------------------------------------
+
+  private fun registerScreenCaptureCallback() {
+    val activity = reactContext.currentActivity ?: return
+    mainHandler.post {
+      val executor = Executor { command -> mainHandler.post(command) }
+      val callback = Activity.ScreenCaptureCallback {
+        onScreenshotDetected()
+      }
+      screenCaptureCallback = callback
+      try {
+        activity.registerScreenCaptureCallback(executor, callback)
+      } catch (e: Exception) {
+        // Fall back to the content observer if the callback can't be registered.
+        registerContentObserver()
+      }
+    }
+  }
+
+  private fun unregisterScreenCaptureCallback() {
+    val activity = reactContext.currentActivity ?: return
+    val callback = screenCaptureCallback as? Activity.ScreenCaptureCallback ?: return
+    mainHandler.post {
+      try {
+        activity.unregisterScreenCaptureCallback(callback)
+      } catch (_: Exception) {
+      }
+      screenCaptureCallback = null
+    }
+  }
+
+  // -- Legacy MediaStore observer -------------------------------------------
+
+  private fun registerContentObserver() {
+    if (contentObserver != null) return
+    val observer = object : ContentObserver(mainHandler) {
+      private var lastDetectedMs = 0L
+
+      override fun onChange(selfChange: Boolean, uri: Uri?) {
+        super.onChange(selfChange, uri)
+        if (!isScreenshotUri(uri)) return
+        // Debounce: MediaStore can fire several times for one screenshot.
+        val now = System.currentTimeMillis()
+        if (now - lastDetectedMs < 1500) return
+        lastDetectedMs = now
+        onScreenshotDetected()
+      }
+    }
+    contentObserver = observer
+    reactContext.contentResolver.registerContentObserver(
+      MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
+      true,
+      observer
+    )
+  }
+
+  private fun isScreenshotUri(uri: Uri?): Boolean {
+    if (uri == null) return true // Some OEMs notify on the table root.
+    val path = uri.toString().lowercase()
+    return path.contains("screenshot") || path.contains("media")
+  }
+
+  // -- Capture & emit --------------------------------------------------------
+
+  private fun onScreenshotDetected() {
+    val activity = reactContext.currentActivity
+    val rootView = activity?.window?.decorView?.rootView
+    if (activity == null || rootView == null) {
+      emit(null, 0, 0)
+      return
+    }
+    captureView(activity, rootView) { bitmap ->
+      if (bitmap == null) {
+        emit(null, 0, 0)
+        return@captureView
+      }
+      val uri = persistBitmap(bitmap)
+      emit(uri, bitmap.width, bitmap.height)
+    }
+  }
+
+  private fun captureView(activity: Activity, view: View, onResult: (Bitmap?) -> Unit) {
+    if (Build.VERSION.SDK_INT >= 26) {
+      try {
+        val bitmap = Bitmap.createBitmap(view.width, view.height, Bitmap.Config.ARGB_8888)
+        val location = IntArray(2)
+        view.getLocationInWindow(location)
+        PixelCopy.request(
+          activity.window,
+          android.graphics.Rect(
+            location[0],
+            location[1],
+            location[0] + view.width,
+            location[1] + view.height
+          ),
+          bitmap,
+          { result ->
+            if (result == PixelCopy.SUCCESS) onResult(bitmap) else drawFallback(view, onResult)
+          },
+          mainHandler
+        )
+        return
+      } catch (e: Exception) {
+        // fall through to canvas draw
+      }
+    }
+    drawFallback(view, onResult)
+  }
+
+  private fun drawFallback(view: View, onResult: (Bitmap?) -> Unit) {
+    try {
+      if (view.width <= 0 || view.height <= 0) {
+        onResult(null)
+        return
+      }
+      val bitmap = Bitmap.createBitmap(view.width, view.height, Bitmap.Config.ARGB_8888)
+      val canvas = android.graphics.Canvas(bitmap)
+      view.draw(canvas)
+      onResult(bitmap)
+    } catch (e: Exception) {
+      onResult(null)
+    }
+  }
+
+  private fun persistBitmap(bitmap: Bitmap): String? {
+    return try {
+      val fileName = "bugreport_${System.currentTimeMillis()}.png"
+      val file = File(reactContext.cacheDir, fileName)
+      FileOutputStream(file).use { out ->
+        bitmap.compress(Bitmap.CompressFormat.PNG, 90, out)
+      }
+      Uri.fromFile(file).toString()
+    } catch (e: Exception) {
+      null
+    }
+  }
+
+  private fun emit(uri: String?, width: Int, height: Int) {
+    val params: WritableMap = Arguments.createMap().apply {
+      if (uri == null) putNull("uri") else putString("uri", uri)
+      putInt("width", width)
+      putInt("height", height)
+    }
+    reactContext
+      .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+      .emit("BugReporterScreenshotTaken", params)
+  }
+
+  companion object {
+    const val NAME = "RNBugReporterScreenshot"
+  }
+}

package/android/src/main/java/com/bugreporter/ScreenshotDetectorPackage.kt

@@ -0,0 +1,20 @@
+package com.bugreporter
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * Registers the screenshot detector native module. Add this to the package list
+ * in MainApplication.kt.
+ */
+class ScreenshotDetectorPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+    return listOf(ScreenshotDetectorModule(reactContext))
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return emptyList()
+  }
+}

package/ios/RNBugReporterScreenshot.m

@@ -0,0 +1,11 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+// Bridges the Swift RNBugReporterScreenshot class into the React Native runtime.
+// Works in both the legacy bridge and bridgeless (new architecture) via interop.
+@interface RCT_EXTERN_MODULE(RNBugReporterScreenshot, RCTEventEmitter)
+
+RCT_EXTERN_METHOD(start)
+RCT_EXTERN_METHOD(stop)
+
+@end

package/ios/RNBugReporterScreenshot.swift

@@ -0,0 +1,113 @@
+import Foundation
+import UIKit
+import React
+
+/**
+ * Native screenshot detector for iOS.
+ *
+ * Listens for `UIApplication.userDidTakeScreenshotNotification` (no special
+ * permission required) and, when the user takes a screenshot, snapshots the
+ * current key window into a PNG in the temp directory. The JS side receives a
+ * `BugReporterScreenshotTaken` event carrying the file URI and dimensions.
+ *
+ * Snapshotting the app window (instead of reading the Photos library) keeps the
+ * SDK permission-free and guarantees we attach exactly what the user saw.
+ */
+@objc(RNBugReporterScreenshot)
+class RNBugReporterScreenshot: RCTEventEmitter {
+
+  private var hasListeners = false
+  private var observer: NSObjectProtocol?
+
+  override init() {
+    super.init()
+  }
+
+  deinit {
+    if let observer = observer {
+      NotificationCenter.default.removeObserver(observer)
+    }
+  }
+
+  @objc override static func requiresMainQueueSetup() -> Bool {
+    return false
+  }
+
+  override func supportedEvents() -> [String]! {
+    return ["BugReporterScreenshotTaken"]
+  }
+
+  override func startObserving() {
+    hasListeners = true
+    observer = NotificationCenter.default.addObserver(
+      forName: UIApplication.userDidTakeScreenshotNotification,
+      object: nil,
+      queue: .main
+    ) { [weak self] _ in
+      self?.handleScreenshot()
+    }
+  }
+
+  override func stopObserving() {
+    hasListeners = false
+    if let observer = observer {
+      NotificationCenter.default.removeObserver(observer)
+      self.observer = nil
+    }
+  }
+
+  /// Manually start detection from JS (idempotent — startObserving handles it).
+  @objc func start() {
+    // No-op: RCTEventEmitter calls startObserving when JS adds a listener.
+  }
+
+  @objc func stop() {
+    // No-op: RCTEventEmitter calls stopObserving when JS removes listeners.
+  }
+
+  private func handleScreenshot() {
+    guard hasListeners else { return }
+
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+      guard let window = self.keyWindow() else {
+        self.sendEvent(withName: "BugReporterScreenshotTaken", body: ["uri": NSNull()])
+        return
+      }
+
+      let renderer = UIGraphicsImageRenderer(bounds: window.bounds)
+      let image = renderer.image { _ in
+        window.drawHierarchy(in: window.bounds, afterScreenUpdates: false)
+      }
+
+      guard let data = image.pngData() else {
+        self.sendEvent(withName: "BugReporterScreenshotTaken", body: ["uri": NSNull()])
+        return
+      }
+
+      let fileName = "bugreport_\(Int(Date().timeIntervalSince1970 * 1000)).png"
+      let fileURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(fileName)
+
+      do {
+        try data.write(to: fileURL, options: .atomic)
+        self.sendEvent(
+          withName: "BugReporterScreenshotTaken",
+          body: [
+            "uri": fileURL.absoluteString,
+            "width": image.size.width * image.scale,
+            "height": image.size.height * image.scale,
+          ]
+        )
+      } catch {
+        self.sendEvent(withName: "BugReporterScreenshotTaken", body: ["uri": NSNull()])
+      }
+    }
+  }
+
+  private func keyWindow() -> UIWindow? {
+    return UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .flatMap { $0.windows }
+      .first(where: { $0.isKeyWindow }) ?? UIApplication.shared.windows.first
+  }
+}