@bbearai/core 0.5.4 → 0.7.0

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 {
@@ -132,12 +143,39 @@ interface HostUserInfo {
     name?: string;
 }
 interface BugBearConfig {
-    /** Your BugBear project ID */
-    projectId: string;
-    /** Supabase URL for the BugBear backend */
-    supabaseUrl: string;
-    /** Supabase anon key for the BugBear backend */
-    supabaseAnonKey: string;
+    /**
+     * BugBear API key (recommended).
+     * When provided, the SDK resolves projectId, supabaseUrl, and supabaseAnonKey
+     * automatically from the BugBear API. This is the simplest config path —
+     * only one env var needed.
+     *
+     * Get yours at https://app.bugbear.ai/settings/projects
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the BugBear dashboard API.
+     * Defaults to 'https://app.bugbear.ai'. Only change this for
+     * self-hosted or local development environments.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Your BugBear project ID.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    projectId?: string;
+    /**
+     * Supabase URL for the BugBear backend.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    supabaseUrl?: string;
+    /**
+     * Supabase anon key for the BugBear backend.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    supabaseAnonKey?: string;
     /** Enable voice input */
     enableVoice?: boolean;
     /** Enable screenshot capture */
@@ -194,7 +232,77 @@ 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' (default), 'light', or 'auto' (follows system preference). */
+type WidgetColorScheme = 'dark' | 'light' | 'auto';
 interface BugBearTheme {
     /** Primary brand color */
     primaryColor?: string;
@@ -204,6 +312,8 @@ interface BugBearTheme {
     textColor?: string;
     /** Border radius */
     borderRadius?: number;
+    /** Color scheme for the widget. Defaults to 'dark'. */
+    colorScheme?: WidgetColorScheme;
 }
 type TestTemplate = 'steps' | 'checklist' | 'rubric' | 'freeform';
 type RubricMode = 'pass_fail' | 'rating';
@@ -338,6 +448,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;
@@ -764,6 +876,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
@@ -778,7 +1039,42 @@ 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.
+     * For the apiKey path, this resolves after credentials are fetched from /api/v1/config.
+     */
+    private pendingInit;
+    /** Whether the client has been successfully initialized. */
+    private initialized;
+    /** Initialization error, if any. */
+    private initError;
     constructor(config: BugBearConfig);
+    /** Whether the client is ready for requests. */
+    get isReady(): boolean;
+    /** Wait until the client is ready. Throws if initialization failed. */
+    ready(): Promise<void>;
+    /**
+     * Resolve Supabase credentials from a BugBear API key.
+     * Checks localStorage cache first, falls back to /api/v1/config.
+     */
+    private resolveFromApiKey;
+    /** Apply resolved credentials and create the Supabase client. */
+    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. */
+    private writeConfigCache;
+    /** Simple string hash for cache keys — avoids storing raw API keys. */
+    private hashKey;
+    /** Ensure the client is initialized before making requests. */
+    private ensureReady;
     /**
      * Access the offline queue (if enabled).
      * Use this to check queue.count, subscribe to changes, or trigger flush.
@@ -989,10 +1285,25 @@ declare class BugBearClient {
      */
     isQAEnabled(): Promise<boolean>;
     /**
-     * Check if the widget should be visible
-     * (QA mode enabled AND current user is a tester)
+     * Check if the widget should be visible.
+     * Behavior depends on the configured mode:
+     * - 'qa': QA enabled AND user is a registered tester
+     * - 'feedback': Any authenticated user
+     * - 'auto': Either QA tester OR authenticated non-tester
      */
     shouldShowWidget(): Promise<boolean>;
+    /**
+     * Resolve the effective widget mode for the current user.
+     * - 'qa' or 'feedback' config → returned as-is
+     * - 'auto' → checks if user is a QA tester (role='tester') → 'qa', otherwise 'feedback'
+     */
+    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)
      */
@@ -1173,6 +1484,7 @@ declare class ContextCaptureManager {
     private navigationHistory;
     private originalConsole;
     private originalFetch?;
+    private fetchHost;
     private originalPushState?;
     private originalReplaceState?;
     private popstateHandler?;
@@ -1231,4 +1543,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, captureError, contextCapture, createBugBear, generateFingerprint, isBugCategory, isNetworkError, scrubUrl };