@bbearai/core 0.6.0 → 0.7.1

package/dist/index.d.mts

@@ -2,6 +2,15 @@
  * BugBear Core Types
  */
 type ReportType = 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
+/**
+ * Widget operating mode:
+ * - 'qa': Full QA widget. Only visible to registered testers when QA is enabled.
+ * - 'feedback': Feedback-only widget. Visible to ALL authenticated users.
+ *   Hides QA flows (tests, sessions). Shows: bug reporting, feedback, messaging, issues.
+ * - 'auto': Auto-detect based on user role. Registered testers → QA mode.
+ *   Authenticated non-testers → feedback mode (auto-provisioned).
+ */
+type BugBearMode = 'qa' | 'feedback' | 'auto';
 type Severity = 'critical' | 'high' | 'medium' | 'low';
 /** Valid bug categories - single source of truth */
 declare const BUG_CATEGORIES: readonly ["ui_ux", "functional", "crash", "security", "other"];
@@ -121,6 +130,8 @@ interface BugBearReport {
     testCaseId?: string;
     /** Enhanced debugging context */
     enhancedContext?: EnhancedBugContext;
+    /** How this report was created. Defaults to 'manual' for widget-submitted reports. */
+    reportSource?: ReportSource;
 }
 /** User info from the host application */
 interface HostUserInfo {
@@ -221,6 +232,81 @@ interface BugBearConfig {
     realtime?: {
         enabled: boolean;
     };
+    /**
+     * Widget operating mode. Controls which features are visible.
+     * - 'qa' (default): Full QA widget for registered testers.
+     * - 'feedback': Feedback-only mode for all authenticated users.
+     * - 'auto': Auto-detect — testers get QA, everyone else gets feedback.
+     */
+    mode?: BugBearMode;
+    /**
+     * Enable automatic error monitoring.
+     * When configured, the SDK auto-detects crashes, API failures, and rage clicks
+     * and submits them as reports with report_source tagging.
+     */
+    monitoring?: MonitoringConfig;
+}
+/**
+ * Report source — distinguishes auto-detected reports from manual ones.
+ */
+type ReportSource = 'manual' | 'auto_crash' | 'auto_api' | 'auto_rage_click' | 'sentry_sync';
+/**
+ * Configuration for automatic error monitoring.
+ * When enabled, the SDK auto-detects production errors and submits them as reports.
+ */
+interface MonitoringConfig {
+    /** Capture unhandled errors and promise rejections (default: false) */
+    crashes?: boolean;
+    /** Capture HTTP 4xx/5xx responses from fetch (default: false) */
+    apiFailures?: boolean;
+    /** Capture rapid repeated clicks with no UI response (default: false) */
+    rageClicks?: boolean;
+    /** Fraction of events to report: 0–1 (default: 1.0) */
+    sampleRate?: number;
+    /** Max auto-reports per session (default: 10) */
+    maxReportsPerSession?: number;
+    /** Window in ms for deduplicating same-fingerprint events (default: 300000 = 5 min) */
+    dedupWindowMs?: number;
+    /** Only report events at or above this severity (default: 'low') */
+    severityThreshold?: Severity;
+    /** Called before submitting — return false to suppress this event */
+    beforeCapture?: (event: MonitoringEvent) => boolean;
+    /** Strip auth tokens, passwords, keys from captured URLs (default: true) */
+    scrubUrls?: boolean;
+}
+/**
+ * A captured monitoring event before it becomes a report.
+ * Passed to beforeCapture for filtering.
+ */
+interface MonitoringEvent {
+    source: 'crash' | 'api_failure' | 'rage_click';
+    fingerprint: string;
+    message: string;
+    route: string;
+    timestamp: number;
+    /** The original error (crashes only) */
+    error?: Error;
+    /** Request URL (API failures only) */
+    requestUrl?: string;
+    /** HTTP method (API failures only) */
+    requestMethod?: string;
+    /** HTTP status code (API failures only) */
+    statusCode?: number;
+    /** Number of rapid clicks detected (rage clicks only) */
+    clickCount?: number;
+    /** CSS selector of the clicked element (rage clicks only) */
+    targetSelector?: string;
+    /** Sentry event ID — populated by @bbearai/sentry adapter */
+    sentryEventId?: string;
+    /** Sentry breadcrumbs — populated by @bbearai/sentry adapter */
+    sentryBreadcrumbs?: unknown[];
+}
+/** Widget color scheme: 'dark', 'light', or 'auto' (follows system preference, default). */
+type WidgetColorScheme = 'dark' | 'light' | 'auto';
+/** Server-side widget configuration set by the project admin in the dashboard. */
+interface WidgetConfig {
+    /** Admin-forced color scheme. When set, overrides the developer's config and user's OS preference. */
+    colorScheme?: WidgetColorScheme;
 }
 interface BugBearTheme {
     /** Primary brand color */
@@ -231,6 +317,8 @@ interface BugBearTheme {
     textColor?: string;
     /** Border radius */
     borderRadius?: number;
+    /** Color scheme for the widget. Defaults to 'auto' (follows OS preference). */
+    colorScheme?: WidgetColorScheme;
 }
 type TestTemplate = 'steps' | 'checklist' | 'rubric' | 'freeform';
 type RubricMode = 'pass_fail' | 'rating';
@@ -365,6 +453,8 @@ interface TesterInfo {
     platforms: string[];
     assignedTests: number;
     completedTests: number;
+    /** Role: 'tester' for QA testers, 'feedback' for feedback-only users */
+    role?: 'tester' | 'feedback';
 }
 interface TesterProfileUpdate {
     name?: string;
@@ -791,6 +881,155 @@ declare class OfflineQueue {
 /** Heuristic: does this error string look like a connectivity failure? */
 declare function isNetworkError(error?: string | null): boolean;
 
+interface MonitorDeps {
+    submitReport: (report: Record<string, unknown>) => Promise<{
+        success: boolean;
+        reportId?: string;
+        error?: string;
+        queued?: boolean;
+    }>;
+    getCurrentRoute: () => string;
+    getEnhancedContext: () => EnhancedBugContext;
+    getDeviceInfo: () => DeviceInfo;
+}
+declare class ErrorMonitor {
+    private deps;
+    private dedup;
+    private sessionReportCount;
+    private config;
+    private pendingSentryData;
+    constructor(config: MonitoringConfig, deps: MonitorDeps);
+    handleEvent(event: MonitoringEvent): Promise<void>;
+    enrichWithSentry(data: {
+        sentryEventId?: string;
+        sentryBreadcrumbs?: unknown[];
+    }): void;
+    private getSeverity;
+    private generateTitle;
+    destroy(): void;
+}
+
+/**
+ * Generate a stable fingerprint for deduplicating monitoring events.
+ * Same source + message + route = same fingerprint.
+ */
+declare function generateFingerprint(source: string, message: string, route: string): string;
+/**
+ * Sliding-window deduplication.
+ * Tracks fingerprints and suppresses duplicates within a configurable time window.
+ */
+declare class DedupWindow {
+    private windowMs;
+    private seen;
+    constructor(windowMs: number);
+    /** Returns true if this fingerprint should be reported (not a recent duplicate). */
+    shouldReport(fingerprint: string): boolean;
+    /** Remove expired entries to prevent memory leaks in long sessions. */
+    private cleanup;
+}
+
+/**
+ * Redact sensitive query parameters from URLs.
+ * Returns the URL with sensitive values replaced by [REDACTED].
+ */
+declare function scrubUrl(url: string): string;
+
+interface RageClickEvent {
+    clickCount: number;
+    targetSelector: string;
+    x: number;
+    y: number;
+}
+/**
+ * Detects rage clicks — 3+ clicks on the same target within 2 seconds.
+ * Platform-agnostic: web passes DOM click data, RN passes touch data.
+ */
+declare class RageClickDetector {
+    private onRageClick;
+    private clicks;
+    private readonly threshold;
+    private readonly windowMs;
+    private destroyed;
+    constructor(onRageClick: (event: RageClickEvent) => void);
+    recordClick(x: number, y: number, targetSelector: string): void;
+    destroy(): void;
+}
+
+type EventCallback = (event: MonitoringEvent) => void;
+declare class WebCrashHandler {
+    private onEvent;
+    private prevOnError;
+    private rejectionHandler;
+    constructor(onEvent: EventCallback);
+    start(): void;
+    destroy(): void;
+}
+declare class WebApiFailureHandler {
+    private onEvent;
+    private originalFetch;
+    constructor(onEvent: EventCallback);
+    start(): void;
+    destroy(): void;
+}
+declare class WebRageClickHandler {
+    private onEvent;
+    private detector;
+    private clickHandler;
+    constructor(onEvent: EventCallback);
+    start(): void;
+    destroy(): void;
+}
+
+/**
+ * React Native crash handler.
+ * Hooks into RN's global ErrorUtils to capture unhandled JS errors.
+ * Chains with the existing handler so RN's default error display (red box) still works.
+ */
+declare class RNCrashHandler {
+    private onEvent;
+    private getCurrentRoute;
+    private originalHandler;
+    private started;
+    constructor(onEvent: (event: MonitoringEvent) => void, getCurrentRoute: () => string);
+    start(): void;
+    destroy(): void;
+}
+/**
+ * React Native API failure handler.
+ * Monkey-patches globalThis.fetch to intercept 4xx/5xx responses.
+ * RN uses the same fetch API as the web, so this is identical in pattern.
+ */
+declare class RNApiFailureHandler {
+    private onEvent;
+    private getCurrentRoute;
+    private originalFetch;
+    private started;
+    constructor(onEvent: (event: MonitoringEvent) => void, getCurrentRoute: () => string);
+    start(): void;
+    destroy(): void;
+}
+/**
+ * React Native rage click handler.
+ * Unlike web, RN doesn't have DOM click events. Instead, exposes a `recordTouch`
+ * method that the BugBearProvider calls from `onTouchEnd` events on the wrapper View.
+ * Internally delegates to RageClickDetector using viewId as the target selector.
+ */
+declare class RNRageClickHandler {
+    private onEvent;
+    private getCurrentRoute;
+    private detector;
+    constructor(onEvent: (event: MonitoringEvent) => void, getCurrentRoute: () => string);
+    start(): void;
+    /**
+     * Record a touch event. Call this from the BugBearProvider's onTouchEnd handler.
+     * @param x - Touch x coordinate
+     * @param y - Touch y coordinate
+     * @param viewId - Identifier for the touched view (e.g., testID, accessibilityLabel, or nativeID)
+     */
+    recordTouch(x: number, y: number, viewId: string): void;
+    destroy(): void;
+}
+
 /**
  * BugBear Client
  * Handles communication with the BugBear backend
@@ -805,6 +1044,8 @@ declare class BugBearClient {
     private _queue;
     /** Active Realtime channel references for cleanup. */
     private realtimeChannels;
+    /** Error monitor instance — created when config.monitoring is present. */
+    monitor: ErrorMonitor | null;
     /**
      * Resolves when the client is ready to make requests.
      * For the explicit config path (supabaseUrl + supabaseAnonKey), this is immediate.
@@ -829,6 +1070,8 @@ declare class BugBearClient {
     private applyResolvedConfig;
     /** Initialize offline queue if configured. Shared by both init paths. */
     private initOfflineQueue;
+    /** Initialize error monitoring if configured. Shared by both init paths. */
+    private initMonitoring;
     /** Read cached config from localStorage if available and not expired. */
     private readConfigCache;
     /** Write resolved config to localStorage cache. */
@@ -1047,10 +1290,35 @@ declare class BugBearClient {
      */
     isQAEnabled(): Promise<boolean>;
     /**
-     * Check if the widget should be visible
-     * (QA mode enabled AND current user is a tester)
+     * Fetch server-side widget config set by the project admin.
+     * Returns settings like color scheme override. Returns empty config on error.
+     */
+    getWidgetConfig(): Promise<WidgetConfig>;
+    /**
+     * Check if feedback mode is enabled for this project.
+     * This is a master switch that admins can toggle in the dashboard.
+     */
+    isFeedbackEnabled(): Promise<boolean>;
+    /**
+     * Check if the widget should be visible.
+     * Behavior depends on the configured mode:
+     * - 'qa': QA enabled AND user is a registered tester
+     * - 'feedback': Feedback enabled AND user is authenticated
+     * - 'auto': QA tester (if QA enabled) OR authenticated user (if feedback enabled)
      */
     shouldShowWidget(): Promise<boolean>;
+    /**
+     * Resolve the effective widget mode for the current user.
+     * - 'qa' or 'feedback' config → returned as-is
+     * - 'auto' → QA tester with QA enabled → 'qa', feedback enabled → 'feedback', else 'qa'
+     */
+    getEffectiveMode(): Promise<'qa' | 'feedback'>;
+    /**
+     * Auto-provision a feedback user record in the testers table.
+     * Called during initialization when mode is 'feedback' or 'auto' for non-testers.
+     * Idempotent — safe to call multiple times. Returns the tester info for the user.
+     */
+    ensureFeedbackUser(): Promise<TesterInfo | null>;
     /**
      * Upload a screenshot (web - uses File/Blob)
      */
@@ -1290,4 +1558,4 @@ declare function captureError(error: Error, errorInfo?: {
     componentStack?: string;
 };
 
-export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, LocalStorageAdapter, type MessageSenderType, type NetworkRequest, OfflineQueue, type OfflineQueueConfig, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type QueueItem, type QueueItemType, type RegressionEvent, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type StorageAdapter, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear, isBugCategory, isNetworkError };
+export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearMode, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, DedupWindow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, ErrorMonitor, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, LocalStorageAdapter, type MessageSenderType, type MonitorDeps, type MonitoringConfig, type MonitoringEvent, type NetworkRequest, OfflineQueue, type OfflineQueueConfig, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type QueueItem, type QueueItemType, RNApiFailureHandler, RNCrashHandler, RNRageClickHandler, RageClickDetector, type RageClickEvent, type RegressionEvent, type ReportSource, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type StorageAdapter, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, WebApiFailureHandler, WebCrashHandler, WebRageClickHandler, type WidgetColorScheme, type WidgetConfig, captureError, contextCapture, createBugBear, generateFingerprint, isBugCategory, isNetworkError, scrubUrl };

package/dist/index.d.ts

@@ -2,6 +2,15 @@
  * BugBear Core Types
  */
 type ReportType = 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
+/**
+ * Widget operating mode:
+ * - 'qa': Full QA widget. Only visible to registered testers when QA is enabled.
+ * - 'feedback': Feedback-only widget. Visible to ALL authenticated users.
+ *   Hides QA flows (tests, sessions). Shows: bug reporting, feedback, messaging, issues.
+ * - 'auto': Auto-detect based on user role. Registered testers → QA mode.
+ *   Authenticated non-testers → feedback mode (auto-provisioned).
+ */
+type BugBearMode = 'qa' | 'feedback' | 'auto';
 type Severity = 'critical' | 'high' | 'medium' | 'low';
 /** Valid bug categories - single source of truth */
 declare const BUG_CATEGORIES: readonly ["ui_ux", "functional", "crash", "security", "other"];
@@ -121,6 +130,8 @@ interface BugBearReport {
     testCaseId?: string;
     /** Enhanced debugging context */
     enhancedContext?: EnhancedBugContext;
+    /** How this report was created. Defaults to 'manual' for widget-submitted reports. */
+    reportSource?: ReportSource;
 }
 /** User info from the host application */
 interface HostUserInfo {
@@ -221,6 +232,81 @@ interface BugBearConfig {
     realtime?: {
         enabled: boolean;
     };
+    /**
+     * Widget operating mode. Controls which features are visible.
+     * - 'qa' (default): Full QA widget for registered testers.
+     * - 'feedback': Feedback-only mode for all authenticated users.
+     * - 'auto': Auto-detect — testers get QA, everyone else gets feedback.
+     */
+    mode?: BugBearMode;
+    /**
+     * Enable automatic error monitoring.
+     * When configured, the SDK auto-detects crashes, API failures, and rage clicks
+     * and submits them as reports with report_source tagging.
+     */
+    monitoring?: MonitoringConfig;
+}
+/**
+ * Report source — distinguishes auto-detected reports from manual ones.
+ */
+type ReportSource = 'manual' | 'auto_crash' | 'auto_api' | 'auto_rage_click' | 'sentry_sync';
+/**
+ * Configuration for automatic error monitoring.
+ * When enabled, the SDK auto-detects production errors and submits them as reports.
+ */
+interface MonitoringConfig {
+    /** Capture unhandled errors and promise rejections (default: false) */
+    crashes?: boolean;
+    /** Capture HTTP 4xx/5xx responses from fetch (default: false) */
+    apiFailures?: boolean;
+    /** Capture rapid repeated clicks with no UI response (default: false) */
+    rageClicks?: boolean;
+    /** Fraction of events to report: 0–1 (default: 1.0) */
+    sampleRate?: number;
+    /** Max auto-reports per session (default: 10) */
+    maxReportsPerSession?: number;
+    /** Window in ms for deduplicating same-fingerprint events (default: 300000 = 5 min) */
+    dedupWindowMs?: number;
+    /** Only report events at or above this severity (default: 'low') */
+    severityThreshold?: Severity;
+    /** Called before submitting — return false to suppress this event */
+    beforeCapture?: (event: MonitoringEvent) => boolean;
+    /** Strip auth tokens, passwords, keys from captured URLs (default: true) */
+    scrubUrls?: boolean;
+}
+/**
+ * A captured monitoring event before it becomes a report.
+ * Passed to beforeCapture for filtering.
+ */
+interface MonitoringEvent {
+    source: 'crash' | 'api_failure' | 'rage_click';
+    fingerprint: string;
+    message: string;
+    route: string;
+    timestamp: number;
+    /** The original error (crashes only) */
+    error?: Error;
+    /** Request URL (API failures only) */
+    requestUrl?: string;
+    /** HTTP method (API failures only) */
+    requestMethod?: string;
+    /** HTTP status code (API failures only) */
+    statusCode?: number;
+    /** Number of rapid clicks detected (rage clicks only) */
+    clickCount?: number;
+    /** CSS selector of the clicked element (rage clicks only) */
+    targetSelector?: string;
+    /** Sentry event ID — populated by @bbearai/sentry adapter */
+    sentryEventId?: string;
+    /** Sentry breadcrumbs — populated by @bbearai/sentry adapter */
+    sentryBreadcrumbs?: unknown[];
+}
+/** Widget color scheme: 'dark', 'light', or 'auto' (follows system preference, default). */
+type WidgetColorScheme = 'dark' | 'light' | 'auto';
+/** Server-side widget configuration set by the project admin in the dashboard. */
+interface WidgetConfig {
+    /** Admin-forced color scheme. When set, overrides the developer's config and user's OS preference. */
+    colorScheme?: WidgetColorScheme;
 }
 interface BugBearTheme {
     /** Primary brand color */
@@ -231,6 +317,8 @@ interface BugBearTheme {
     textColor?: string;
     /** Border radius */
     borderRadius?: number;
+    /** Color scheme for the widget. Defaults to 'auto' (follows OS preference). */
+    colorScheme?: WidgetColorScheme;
 }
 type TestTemplate = 'steps' | 'checklist' | 'rubric' | 'freeform';
 type RubricMode = 'pass_fail' | 'rating';
@@ -365,6 +453,8 @@ interface TesterInfo {
     platforms: string[];
     assignedTests: number;
     completedTests: number;
+    /** Role: 'tester' for QA testers, 'feedback' for feedback-only users */
+    role?: 'tester' | 'feedback';
 }
 interface TesterProfileUpdate {
     name?: string;
@@ -791,6 +881,155 @@ declare class OfflineQueue {
 /** Heuristic: does this error string look like a connectivity failure? */
 declare function isNetworkError(error?: string | null): boolean;
 
+interface MonitorDeps {
+    submitReport: (report: Record<string, unknown>) => Promise<{
+        success: boolean;
+        reportId?: string;
+        error?: string;
+        queued?: boolean;
+    }>;
+    getCurrentRoute: () => string;
+    getEnhancedContext: () => EnhancedBugContext;
+    getDeviceInfo: () => DeviceInfo;
+}
+declare class ErrorMonitor {
+    private deps;
+    private dedup;
+    private sessionReportCount;
+    private config;
+    private pendingSentryData;
+    constructor(config: MonitoringConfig, deps: MonitorDeps);
+    handleEvent(event: MonitoringEvent): Promise<void>;
+    enrichWithSentry(data: {
+        sentryEventId?: string;
+        sentryBreadcrumbs?: unknown[];
+    }): void;
+    private getSeverity;
+    private generateTitle;
+    destroy(): void;
+}
+
+/**
+ * Generate a stable fingerprint for deduplicating monitoring events.
+ * Same source + message + route = same fingerprint.
+ */
+declare function generateFingerprint(source: string, message: string, route: string): string;
+/**
+ * Sliding-window deduplication.
+ * Tracks fingerprints and suppresses duplicates within a configurable time window.
+ */
+declare class DedupWindow {
+    private windowMs;
+    private seen;
+    constructor(windowMs: number);
+    /** Returns true if this fingerprint should be reported (not a recent duplicate). */
+    shouldReport(fingerprint: string): boolean;
+    /** Remove expired entries to prevent memory leaks in long sessions. */
+    private cleanup;
+}
+
+/**
+ * Redact sensitive query parameters from URLs.
+ * Returns the URL with sensitive values replaced by [REDACTED].
+ */
+declare function scrubUrl(url: string): string;
+
+interface RageClickEvent {
+    clickCount: number;
+    targetSelector: string;
+    x: number;
+    y: number;
+}
+/**
+ * Detects rage clicks — 3+ clicks on the same target within 2 seconds.
+ * Platform-agnostic: web passes DOM click data, RN passes touch data.
+ */
+declare class RageClickDetector {
+    private onRageClick;
+    private clicks;
+    private readonly threshold;
+    private readonly windowMs;
+    private destroyed;
+    constructor(onRageClick: (event: RageClickEvent) => void);
+    recordClick(x: number, y: number, targetSelector: string): void;
+    destroy(): void;
+}
+
+type EventCallback = (event: MonitoringEvent) => void;
+declare class WebCrashHandler {
+    private onEvent;
+    private prevOnError;
+    private rejectionHandler;
+    constructor(onEvent: EventCallback);
+    start(): void;
+    destroy(): void;
+}
+declare class WebApiFailureHandler {
+    private onEvent;
+    private originalFetch;
+    constructor(onEvent: EventCallback);
+    start(): void;
+    destroy(): void;
+}
+declare class WebRageClickHandler {
+    private onEvent;
+    private detector;
+    private clickHandler;
+    constructor(onEvent: EventCallback);
+    start(): void;
+    destroy(): void;
+}
+
+/**
+ * React Native crash handler.
+ * Hooks into RN's global ErrorUtils to capture unhandled JS errors.
+ * Chains with the existing handler so RN's default error display (red box) still works.
+ */
+declare class RNCrashHandler {
+    private onEvent;
+    private getCurrentRoute;
+    private originalHandler;
+    private started;
+    constructor(onEvent: (event: MonitoringEvent) => void, getCurrentRoute: () => string);
+    start(): void;
+    destroy(): void;
+}
+/**
+ * React Native API failure handler.
+ * Monkey-patches globalThis.fetch to intercept 4xx/5xx responses.
+ * RN uses the same fetch API as the web, so this is identical in pattern.
+ */
+declare class RNApiFailureHandler {
+    private onEvent;
+    private getCurrentRoute;
+    private originalFetch;
+    private started;
+    constructor(onEvent: (event: MonitoringEvent) => void, getCurrentRoute: () => string);
+    start(): void;
+    destroy(): void;
+}
+/**
+ * React Native rage click handler.
+ * Unlike web, RN doesn't have DOM click events. Instead, exposes a `recordTouch`
+ * method that the BugBearProvider calls from `onTouchEnd` events on the wrapper View.
+ * Internally delegates to RageClickDetector using viewId as the target selector.
+ */
+declare class RNRageClickHandler {
+    private onEvent;
+    private getCurrentRoute;
+    private detector;
+    constructor(onEvent: (event: MonitoringEvent) => void, getCurrentRoute: () => string);
+    start(): void;
+    /**
+     * Record a touch event. Call this from the BugBearProvider's onTouchEnd handler.
+     * @param x - Touch x coordinate
+     * @param y - Touch y coordinate
+     * @param viewId - Identifier for the touched view (e.g., testID, accessibilityLabel, or nativeID)
+     */
+    recordTouch(x: number, y: number, viewId: string): void;
+    destroy(): void;
+}
+
 /**
  * BugBear Client
  * Handles communication with the BugBear backend
@@ -805,6 +1044,8 @@ declare class BugBearClient {
     private _queue;
     /** Active Realtime channel references for cleanup. */
     private realtimeChannels;
+    /** Error monitor instance — created when config.monitoring is present. */
+    monitor: ErrorMonitor | null;
     /**
      * Resolves when the client is ready to make requests.
      * For the explicit config path (supabaseUrl + supabaseAnonKey), this is immediate.
@@ -829,6 +1070,8 @@ declare class BugBearClient {
     private applyResolvedConfig;
     /** Initialize offline queue if configured. Shared by both init paths. */
     private initOfflineQueue;
+    /** Initialize error monitoring if configured. Shared by both init paths. */
+    private initMonitoring;
     /** Read cached config from localStorage if available and not expired. */
     private readConfigCache;
     /** Write resolved config to localStorage cache. */
@@ -1047,10 +1290,35 @@ declare class BugBearClient {
      */
     isQAEnabled(): Promise<boolean>;
     /**
-     * Check if the widget should be visible
-     * (QA mode enabled AND current user is a tester)
+     * Fetch server-side widget config set by the project admin.
+     * Returns settings like color scheme override. Returns empty config on error.
+     */
+    getWidgetConfig(): Promise<WidgetConfig>;
+    /**
+     * Check if feedback mode is enabled for this project.
+     * This is a master switch that admins can toggle in the dashboard.
+     */
+    isFeedbackEnabled(): Promise<boolean>;
+    /**
+     * Check if the widget should be visible.
+     * Behavior depends on the configured mode:
+     * - 'qa': QA enabled AND user is a registered tester
+     * - 'feedback': Feedback enabled AND user is authenticated
+     * - 'auto': QA tester (if QA enabled) OR authenticated user (if feedback enabled)
      */
     shouldShowWidget(): Promise<boolean>;
+    /**
+     * Resolve the effective widget mode for the current user.
+     * - 'qa' or 'feedback' config → returned as-is
+     * - 'auto' → QA tester with QA enabled → 'qa', feedback enabled → 'feedback', else 'qa'
+     */
+    getEffectiveMode(): Promise<'qa' | 'feedback'>;
+    /**
+     * Auto-provision a feedback user record in the testers table.
+     * Called during initialization when mode is 'feedback' or 'auto' for non-testers.
+     * Idempotent — safe to call multiple times. Returns the tester info for the user.
+     */
+    ensureFeedbackUser(): Promise<TesterInfo | null>;
     /**
      * Upload a screenshot (web - uses File/Blob)
      */
@@ -1290,4 +1558,4 @@ declare function captureError(error: Error, errorInfo?: {
     componentStack?: string;
 };
 
-export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, LocalStorageAdapter, type MessageSenderType, type NetworkRequest, OfflineQueue, type OfflineQueueConfig, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type QueueItem, type QueueItemType, type RegressionEvent, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type StorageAdapter, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear, isBugCategory, isNetworkError };
+export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearMode, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, DedupWindow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, ErrorMonitor, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, LocalStorageAdapter, type MessageSenderType, type MonitorDeps, type MonitoringConfig, type MonitoringEvent, type NetworkRequest, OfflineQueue, type OfflineQueueConfig, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type QueueItem, type QueueItemType, RNApiFailureHandler, RNCrashHandler, RNRageClickHandler, RageClickDetector, type RageClickEvent, type RegressionEvent, type ReportSource, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type StorageAdapter, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, WebApiFailureHandler, WebCrashHandler, WebRageClickHandler, type WidgetColorScheme, type WidgetConfig, captureError, contextCapture, createBugBear, generateFingerprint, isBugCategory, isNetworkError, scrubUrl };