@bbearai/core 0.7.0 → 0.7.2

package/dist/index.d.mts

@@ -301,8 +301,13 @@ interface MonitoringEvent {
     /** Sentry breadcrumbs — populated by @bbearai/sentry adapter */
     sentryBreadcrumbs?: unknown[];
 }
-/** Widget color scheme: 'dark' (default), 'light', or 'auto' (follows system preference). */
+/** 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 */
     primaryColor?: string;
@@ -312,7 +317,7 @@ interface BugBearTheme {
     textColor?: string;
     /** Border radius */
     borderRadius?: number;
-    /** Color scheme for the widget. Defaults to 'dark'. */
+    /** Color scheme for the widget. Defaults to 'auto' (follows OS preference). */
     colorScheme?: WidgetColorScheme;
 }
 type TestTemplate = 'steps' | 'checklist' | 'rubric' | 'freeform';
@@ -784,6 +789,50 @@ interface TesterIssue {
     /** Original bug title (for reopened/test_fail issues) */
     originalBugTitle?: string;
 }
+/** Delivery status for captured emails */
+type EmailDeliveryStatus = 'pending' | 'sent' | 'delivered' | 'bounced' | 'dropped' | 'deferred';
+/** Email capture mode */
+type EmailCaptureMode = 'capture' | 'intercept';
+/** A captured email payload sent to the BugBear API */
+interface EmailCapturePayload {
+    to: string[];
+    from?: string;
+    subject: string;
+    html?: string;
+    text?: string;
+    templateId?: string;
+    captureMode: EmailCaptureMode;
+    wasDelivered: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Result of capturing an email */
+interface EmailCaptureResult {
+    success: boolean;
+    captureId?: string;
+    queued?: boolean;
+    error?: string;
+}
+/** Options for the email interceptor */
+interface EmailInterceptorOptions {
+    /** 'capture' = log + send, 'intercept' = log + block */
+    mode: EmailCaptureMode;
+    /** Only capture emails sent to these addresses */
+    filterTo?: string[];
+    /** Replace real recipient addresses with "[redacted]" in captures */
+    redactRecipients?: boolean;
+}
+/** Extracted email fields from a send function call */
+interface ExtractedEmailPayload {
+    to: string | string[];
+    from?: string;
+    subject: string;
+    html?: string;
+    text?: string;
+    templateId?: string;
+    [key: string]: unknown;
+}
+/** Custom extractor for non-standard email function signatures */
+type EmailPayloadExtractor = (args: unknown[]) => ExtractedEmailPayload;
 
 /**
  * BugBear Offline Queue
@@ -810,7 +859,7 @@ declare class LocalStorageAdapter implements StorageAdapter {
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
 }
-type QueueItemType = 'report' | 'message' | 'feedback';
+type QueueItemType = 'report' | 'message' | 'feedback' | 'email_capture';
 interface QueueItem {
     /** Unique ID for this queued operation. */
     id: string;
@@ -1037,6 +1086,8 @@ declare class BugBearClient {
     private reportSubmitInFlight;
     /** Offline queue — only created when config.offlineQueue.enabled is true. */
     private _queue;
+    /** Session cache storage — defaults to LocalStorageAdapter. */
+    private _sessionStorage;
     /** Active Realtime channel references for cleanup. */
     private realtimeChannels;
     /** Error monitor instance — created when config.monitoring is present. */
@@ -1063,6 +1114,8 @@ declare class BugBearClient {
     private resolveFromApiKey;
     /** Apply resolved credentials and create the Supabase client. */
     private applyResolvedConfig;
+    /** Cache key scoped to the active project. */
+    private get sessionCacheKey();
     /** Initialize offline queue if configured. Shared by both init paths. */
     private initOfflineQueue;
     /** Initialize error monitoring if configured. Shared by both init paths. */
@@ -1075,6 +1128,12 @@ declare class BugBearClient {
     private hashKey;
     /** Ensure the client is initialized before making requests. */
     private ensureReady;
+    /**
+     * Fire-and-forget call to a dashboard notification endpoint.
+     * Only works when apiKey is configured (needed for API auth).
+     * Failures are silently ignored — notifications are best-effort.
+     */
+    private notifyDashboard;
     /**
      * Access the offline queue (if enabled).
      * Use this to check queue.count, subscribe to changes, or trigger flush.
@@ -1086,6 +1145,22 @@ declare class BugBearClient {
      * Web callers can skip this — LocalStorageAdapter is the default.
      */
     initQueue(storage?: StorageAdapter): Promise<void>;
+    /**
+     * Swap the session cache storage adapter (for React Native — pass AsyncStorage).
+     * Must be called before getCachedSession() for persistence across app kills.
+     * Web callers don't need this — LocalStorageAdapter is the default.
+     */
+    setSessionStorage(adapter: StorageAdapter): void;
+    /**
+     * Cache the active QA session locally for instant restore on app restart.
+     * Pass null to clear the cache (e.g. after ending a session).
+     */
+    cacheSession(session: QASession | null): Promise<void>;
+    /**
+     * Retrieve the cached QA session. Returns null if no cache, if stale (>24h),
+     * or if parsing fails. The DB fetch in initializeBugBear() is the source of truth.
+     */
+    getCachedSession(): Promise<QASession | null>;
     private registerQueueHandlers;
     /** Whether realtime is enabled in config. */
     get realtimeEnabled(): boolean;
@@ -1132,6 +1207,11 @@ declare class BugBearClient {
         queued?: boolean;
         error?: string;
     }>;
+    /**
+     * Capture an email for QA testing.
+     * Called by the email interceptor — not typically called directly.
+     */
+    captureEmail(payload: EmailCapturePayload): Promise<EmailCaptureResult>;
     /**
      * Get assigned tests for current user
      * First looks up the tester by email, then fetches their assignments
@@ -1248,6 +1328,14 @@ declare class BugBearClient {
      * reopened issues include original bug context.
      */
     getIssues(category: 'open' | 'done' | 'reopened'): Promise<TesterIssue[]>;
+    /**
+     * Reopen a done issue that the tester believes isn't actually fixed.
+     * Transitions the report from a done status back to 'confirmed'.
+     */
+    reopenReport(reportId: string, reason: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     /**
      * Basic email format validation (defense in depth)
      */
@@ -1284,18 +1372,28 @@ declare class BugBearClient {
      * This is a master switch that admins can toggle in the dashboard
      */
     isQAEnabled(): Promise<boolean>;
+    /**
+     * 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': Any authenticated user
-     * - 'auto': Either QA tester OR authenticated non-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' → checks if user is a QA tester (role='tester') → 'qa', otherwise 'feedback'
+     * - 'auto' → QA tester with QA enabled → 'qa', feedback enabled → 'feedback', else 'qa'
      */
     getEffectiveMode(): Promise<'qa' | 'feedback'>;
     /**
@@ -1543,4 +1641,26 @@ declare function captureError(error: Error, errorInfo?: {
     componentStack?: string;
 };
 
-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 };
+interface WrapOptions {
+    extractPayload?: EmailPayloadExtractor;
+}
+interface EmailInterceptor {
+    wrap<T extends (...args: any[]) => Promise<any>>(sendFn: T, options?: WrapOptions): T;
+}
+/**
+ * Create an email interceptor that captures emails sent through a wrapped function.
+ *
+ * Two modes:
+ * - `capture`: emails are sent normally AND captured in BugBear (safe for production)
+ * - `intercept`: emails are NOT sent, only captured in BugBear (for staging/QA)
+ *
+ * @example
+ * ```ts
+ * const interceptor = createEmailInterceptor(bugbearClient, { mode: 'intercept' });
+ * const wrappedSend = interceptor.wrap(originalSendEmail);
+ * await wrappedSend({ to: 'user@example.com', subject: 'Test', html: '<p>Hi</p>' });
+ * ```
+ */
+declare function createEmailInterceptor(client: BugBearClient, options?: EmailInterceptorOptions): EmailInterceptor;
+
+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 EmailCaptureMode, type EmailCapturePayload, type EmailCaptureResult, type EmailDeliveryStatus, type EmailInterceptorOptions, type EmailPayloadExtractor, type EndSessionOptions, type EnhancedBugContext, ErrorMonitor, type ExtractedEmailPayload, 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, createEmailInterceptor, generateFingerprint, isBugCategory, isNetworkError, scrubUrl };

package/dist/index.d.ts

@@ -301,8 +301,13 @@ interface MonitoringEvent {
     /** Sentry breadcrumbs — populated by @bbearai/sentry adapter */
     sentryBreadcrumbs?: unknown[];
 }
-/** Widget color scheme: 'dark' (default), 'light', or 'auto' (follows system preference). */
+/** 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 */
     primaryColor?: string;
@@ -312,7 +317,7 @@ interface BugBearTheme {
     textColor?: string;
     /** Border radius */
     borderRadius?: number;
-    /** Color scheme for the widget. Defaults to 'dark'. */
+    /** Color scheme for the widget. Defaults to 'auto' (follows OS preference). */
     colorScheme?: WidgetColorScheme;
 }
 type TestTemplate = 'steps' | 'checklist' | 'rubric' | 'freeform';
@@ -784,6 +789,50 @@ interface TesterIssue {
     /** Original bug title (for reopened/test_fail issues) */
     originalBugTitle?: string;
 }
+/** Delivery status for captured emails */
+type EmailDeliveryStatus = 'pending' | 'sent' | 'delivered' | 'bounced' | 'dropped' | 'deferred';
+/** Email capture mode */
+type EmailCaptureMode = 'capture' | 'intercept';
+/** A captured email payload sent to the BugBear API */
+interface EmailCapturePayload {
+    to: string[];
+    from?: string;
+    subject: string;
+    html?: string;
+    text?: string;
+    templateId?: string;
+    captureMode: EmailCaptureMode;
+    wasDelivered: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Result of capturing an email */
+interface EmailCaptureResult {
+    success: boolean;
+    captureId?: string;
+    queued?: boolean;
+    error?: string;
+}
+/** Options for the email interceptor */
+interface EmailInterceptorOptions {
+    /** 'capture' = log + send, 'intercept' = log + block */
+    mode: EmailCaptureMode;
+    /** Only capture emails sent to these addresses */
+    filterTo?: string[];
+    /** Replace real recipient addresses with "[redacted]" in captures */
+    redactRecipients?: boolean;
+}
+/** Extracted email fields from a send function call */
+interface ExtractedEmailPayload {
+    to: string | string[];
+    from?: string;
+    subject: string;
+    html?: string;
+    text?: string;
+    templateId?: string;
+    [key: string]: unknown;
+}
+/** Custom extractor for non-standard email function signatures */
+type EmailPayloadExtractor = (args: unknown[]) => ExtractedEmailPayload;
 
 /**
  * BugBear Offline Queue
@@ -810,7 +859,7 @@ declare class LocalStorageAdapter implements StorageAdapter {
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
 }
-type QueueItemType = 'report' | 'message' | 'feedback';
+type QueueItemType = 'report' | 'message' | 'feedback' | 'email_capture';
 interface QueueItem {
     /** Unique ID for this queued operation. */
     id: string;
@@ -1037,6 +1086,8 @@ declare class BugBearClient {
     private reportSubmitInFlight;
     /** Offline queue — only created when config.offlineQueue.enabled is true. */
     private _queue;
+    /** Session cache storage — defaults to LocalStorageAdapter. */
+    private _sessionStorage;
     /** Active Realtime channel references for cleanup. */
     private realtimeChannels;
     /** Error monitor instance — created when config.monitoring is present. */
@@ -1063,6 +1114,8 @@ declare class BugBearClient {
     private resolveFromApiKey;
     /** Apply resolved credentials and create the Supabase client. */
     private applyResolvedConfig;
+    /** Cache key scoped to the active project. */
+    private get sessionCacheKey();
     /** Initialize offline queue if configured. Shared by both init paths. */
     private initOfflineQueue;
     /** Initialize error monitoring if configured. Shared by both init paths. */
@@ -1075,6 +1128,12 @@ declare class BugBearClient {
     private hashKey;
     /** Ensure the client is initialized before making requests. */
     private ensureReady;
+    /**
+     * Fire-and-forget call to a dashboard notification endpoint.
+     * Only works when apiKey is configured (needed for API auth).
+     * Failures are silently ignored — notifications are best-effort.
+     */
+    private notifyDashboard;
     /**
      * Access the offline queue (if enabled).
      * Use this to check queue.count, subscribe to changes, or trigger flush.
@@ -1086,6 +1145,22 @@ declare class BugBearClient {
      * Web callers can skip this — LocalStorageAdapter is the default.
      */
     initQueue(storage?: StorageAdapter): Promise<void>;
+    /**
+     * Swap the session cache storage adapter (for React Native — pass AsyncStorage).
+     * Must be called before getCachedSession() for persistence across app kills.
+     * Web callers don't need this — LocalStorageAdapter is the default.
+     */
+    setSessionStorage(adapter: StorageAdapter): void;
+    /**
+     * Cache the active QA session locally for instant restore on app restart.
+     * Pass null to clear the cache (e.g. after ending a session).
+     */
+    cacheSession(session: QASession | null): Promise<void>;
+    /**
+     * Retrieve the cached QA session. Returns null if no cache, if stale (>24h),
+     * or if parsing fails. The DB fetch in initializeBugBear() is the source of truth.
+     */
+    getCachedSession(): Promise<QASession | null>;
     private registerQueueHandlers;
     /** Whether realtime is enabled in config. */
     get realtimeEnabled(): boolean;
@@ -1132,6 +1207,11 @@ declare class BugBearClient {
         queued?: boolean;
         error?: string;
     }>;
+    /**
+     * Capture an email for QA testing.
+     * Called by the email interceptor — not typically called directly.
+     */
+    captureEmail(payload: EmailCapturePayload): Promise<EmailCaptureResult>;
     /**
      * Get assigned tests for current user
      * First looks up the tester by email, then fetches their assignments
@@ -1248,6 +1328,14 @@ declare class BugBearClient {
      * reopened issues include original bug context.
      */
     getIssues(category: 'open' | 'done' | 'reopened'): Promise<TesterIssue[]>;
+    /**
+     * Reopen a done issue that the tester believes isn't actually fixed.
+     * Transitions the report from a done status back to 'confirmed'.
+     */
+    reopenReport(reportId: string, reason: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     /**
      * Basic email format validation (defense in depth)
      */
@@ -1284,18 +1372,28 @@ declare class BugBearClient {
      * This is a master switch that admins can toggle in the dashboard
      */
     isQAEnabled(): Promise<boolean>;
+    /**
+     * 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': Any authenticated user
-     * - 'auto': Either QA tester OR authenticated non-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' → checks if user is a QA tester (role='tester') → 'qa', otherwise 'feedback'
+     * - 'auto' → QA tester with QA enabled → 'qa', feedback enabled → 'feedback', else 'qa'
      */
     getEffectiveMode(): Promise<'qa' | 'feedback'>;
     /**
@@ -1543,4 +1641,26 @@ declare function captureError(error: Error, errorInfo?: {
     componentStack?: string;
 };
 
-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 };
+interface WrapOptions {
+    extractPayload?: EmailPayloadExtractor;
+}
+interface EmailInterceptor {
+    wrap<T extends (...args: any[]) => Promise<any>>(sendFn: T, options?: WrapOptions): T;
+}
+/**
+ * Create an email interceptor that captures emails sent through a wrapped function.
+ *
+ * Two modes:
+ * - `capture`: emails are sent normally AND captured in BugBear (safe for production)
+ * - `intercept`: emails are NOT sent, only captured in BugBear (for staging/QA)
+ *
+ * @example
+ * ```ts
+ * const interceptor = createEmailInterceptor(bugbearClient, { mode: 'intercept' });
+ * const wrappedSend = interceptor.wrap(originalSendEmail);
+ * await wrappedSend({ to: 'user@example.com', subject: 'Test', html: '<p>Hi</p>' });
+ * ```
+ */
+declare function createEmailInterceptor(client: BugBearClient, options?: EmailInterceptorOptions): EmailInterceptor;
+
+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 EmailCaptureMode, type EmailCapturePayload, type EmailCaptureResult, type EmailDeliveryStatus, type EmailInterceptorOptions, type EmailPayloadExtractor, type EndSessionOptions, type EnhancedBugContext, ErrorMonitor, type ExtractedEmailPayload, 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, createEmailInterceptor, generateFingerprint, isBugCategory, isNetworkError, scrubUrl };

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   captureError: () => captureError,
   contextCapture: () => contextCapture,
   createBugBear: () => createBugBear,
+  createEmailInterceptor: () => createEmailInterceptor,
   generateFingerprint: () => generateFingerprint,
   isBugCategory: () => isBugCategory,
   isNetworkError: () => isNetworkError,
@@ -902,6 +903,8 @@ var BugBearClient = class {
     this.reportSubmitInFlight = false;
     /** Offline queue — only created when config.offlineQueue.enabled is true. */
     this._queue = null;
+    /** Session cache storage — defaults to LocalStorageAdapter. */
+    this._sessionStorage = new LocalStorageAdapter();
     /** Active Realtime channel references for cleanup. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this.realtimeChannels = [];
@@ -984,6 +987,10 @@ var BugBearClient = class {
     this.initOfflineQueue();
     this.initMonitoring();
   }
+  /** Cache key scoped to the active project. */
+  get sessionCacheKey() {
+    return `bugbear_session_${this.config.projectId ?? "unknown"}`;
+  }
   /** Initialize offline queue if configured. Shared by both init paths. */
   initOfflineQueue() {
     if (this.config.offlineQueue?.enabled) {
@@ -1047,6 +1054,26 @@ var BugBearClient = class {
     await this.pendingInit;
     if (this.initError) throw this.initError;
   }
+  /**
+   * Fire-and-forget call to a dashboard notification endpoint.
+   * Only works when apiKey is configured (needed for API auth).
+   * Failures are silently ignored — notifications are best-effort.
+   */
+  async notifyDashboard(path, body) {
+    if (!this.config.apiKey) return;
+    try {
+      const baseUrl = (this.config.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, "");
+      await fetch(`${baseUrl}/api/v1/notifications/${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify(body)
+      });
+    } catch {
+    }
+  }
   // ── Offline Queue ─────────────────────────────────────────
   /**
    * Access the offline queue (if enabled).
@@ -1073,6 +1100,48 @@ var BugBearClient = class {
     }
     await this._queue.load();
   }
+  // ── Session Cache ──────────────────────────────────────────
+  /**
+   * Swap the session cache storage adapter (for React Native — pass AsyncStorage).
+   * Must be called before getCachedSession() for persistence across app kills.
+   * Web callers don't need this — LocalStorageAdapter is the default.
+   */
+  setSessionStorage(adapter) {
+    this._sessionStorage = adapter;
+  }
+  /**
+   * Cache the active QA session locally for instant restore on app restart.
+   * Pass null to clear the cache (e.g. after ending a session).
+   */
+  async cacheSession(session) {
+    try {
+      if (session) {
+        await this._sessionStorage.setItem(this.sessionCacheKey, JSON.stringify(session));
+      } else {
+        await this._sessionStorage.removeItem(this.sessionCacheKey);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Retrieve the cached QA session. Returns null if no cache, if stale (>24h),
+   * or if parsing fails. The DB fetch in initializeBugBear() is the source of truth.
+   */
+  async getCachedSession() {
+    try {
+      const raw = await this._sessionStorage.getItem(this.sessionCacheKey);
+      if (!raw) return null;
+      const session = JSON.parse(raw);
+      const age = Date.now() - new Date(session.startedAt).getTime();
+      if (age > 24 * 60 * 60 * 1e3) {
+        await this._sessionStorage.removeItem(this.sessionCacheKey);
+        return null;
+      }
+      return session;
+    } catch {
+      return null;
+    }
+  }
   registerQueueHandlers() {
     if (!this._queue) return;
     this._queue.registerHandler("report", async (payload) => {
@@ -1090,6 +1159,11 @@ var BugBearClient = class {
       if (error) return { success: false, error: error.message };
       return { success: true };
     });
+    this._queue.registerHandler("email_capture", async (payload) => {
+      const { error } = await this.supabase.from("email_captures").insert(payload).select("id").single();
+      if (error) return { success: false, error: error.message };
+      return { success: true };
+    });
   }
   // ── Realtime Subscriptions ─────────────────────────────────
   /** Whether realtime is enabled in config. */
@@ -1277,6 +1351,8 @@ var BugBearClient = class {
       if (this.config.onReportSubmitted) {
         this.config.onReportSubmitted(report);
       }
+      this.notifyDashboard("report", { reportId: data.id }).catch(() => {
+      });
       return { success: true, reportId: data.id };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -1289,6 +1365,44 @@ var BugBearClient = class {
       this.reportSubmitInFlight = false;
     }
   }
+  /**
+   * Capture an email for QA testing.
+   * Called by the email interceptor — not typically called directly.
+   */
+  async captureEmail(payload) {
+    try {
+      await this.ready();
+      if (!payload.subject || !payload.to || payload.to.length === 0) {
+        return { success: false, error: "subject and to are required" };
+      }
+      const record = {
+        project_id: this.config.projectId,
+        to_addresses: payload.to,
+        from_address: payload.from || null,
+        subject: payload.subject,
+        html_content: payload.html || null,
+        text_content: payload.text || null,
+        template_id: payload.templateId || null,
+        metadata: payload.metadata || {},
+        capture_mode: payload.captureMode,
+        was_delivered: payload.wasDelivered,
+        delivery_status: payload.wasDelivered ? "sent" : "pending"
+      };
+      const { data, error } = await this.supabase.from("email_captures").insert(record).select("id").single();
+      if (error) {
+        if (this._queue && isNetworkError(error.message)) {
+          await this._queue.enqueue("email_capture", record);
+          return { success: false, queued: true, error: "Queued \u2014 will send when online" };
+        }
+        console.error("BugBear: Failed to capture email", error.message);
+        return { success: false, error: error.message };
+      }
+      return { success: true, captureId: data.id };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return { success: false, error: message };
+    }
+  }
   /**
    * Get assigned tests for current user
    * First looks up the tester by email, then fetches their assignments
@@ -1910,6 +2024,32 @@ var BugBearClient = class {
       return [];
     }
   }
+  /**
+   * Reopen a done issue that the tester believes isn't actually fixed.
+   * Transitions the report from a done status back to 'confirmed'.
+   */
+  async reopenReport(reportId, reason) {
+    try {
+      const testerInfo = await this.getTesterInfo();
+      if (!testerInfo) return { success: false, error: "Not authenticated as tester" };
+      const { data, error } = await this.supabase.rpc("reopen_report", {
+        p_report_id: reportId,
+        p_tester_id: testerInfo.id,
+        p_reason: reason
+      });
+      if (error) {
+        console.error("BugBear: Failed to reopen report", formatPgError(error));
+        return { success: false, error: error.message };
+      }
+      if (!data?.success) {
+        return { success: false, error: data?.error || "Failed to reopen report" };
+      }
+      return { success: true };
+    } catch (err) {
+      console.error("BugBear: Error reopening report", err);
+      return { success: false, error: "Unexpected error" };
+    }
+  }
   /**
    * Basic email format validation (defense in depth)
    */
@@ -2102,12 +2242,56 @@ var BugBearClient = class {
       return true;
     }
   }
+  /**
+   * Fetch server-side widget config set by the project admin.
+   * Returns settings like color scheme override. Returns empty config on error.
+   */
+  async getWidgetConfig() {
+    try {
+      await this.ensureReady();
+      const { data, error } = await this.supabase.rpc("get_widget_config", {
+        p_project_id: this.config.projectId
+      });
+      if (error) {
+        console.warn("BugBear: Could not fetch widget config", error.message || error.code || "Unknown error");
+        return {};
+      }
+      return data ?? {};
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error fetching widget config";
+      console.error("BugBear: Error fetching widget config", err);
+      this.config.onError?.(err instanceof Error ? err : new Error(message), { projectId: this.config.projectId });
+      return {};
+    }
+  }
+  /**
+   * Check if feedback mode is enabled for this project.
+   * This is a master switch that admins can toggle in the dashboard.
+   */
+  async isFeedbackEnabled() {
+    try {
+      await this.ensureReady();
+      const { data, error } = await this.supabase.rpc("check_feedback_enabled", {
+        p_project_id: this.config.projectId
+      });
+      if (error) {
+        console.warn("BugBear: Could not check feedback status", error.message || error.code || "Unknown error");
+        return false;
+      }
+      return data ?? false;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error checking feedback status";
+      console.error("BugBear: Error checking feedback status", err);
+      this.config.onError?.(err instanceof Error ? err : new Error(message), { projectId: this.config.projectId });
+      return false;
+    }
+  }
   /**
    * 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
+   * - 'feedback': Feedback enabled AND user is authenticated
+   * - 'auto': QA tester (if QA enabled) OR authenticated user (if feedback enabled)
    */
   async shouldShowWidget() {
     const mode = this.config.mode || "qa";
@@ -2119,33 +2303,39 @@ var BugBearClient = class {
       return qaEnabled2 && tester;
     }
     if (mode === "feedback") {
-      const userInfo2 = await this.getCurrentUserInfo();
-      return userInfo2 !== null;
+      const [feedbackEnabled2, userInfo2] = await Promise.all([
+        this.isFeedbackEnabled(),
+        this.getCurrentUserInfo()
+      ]);
+      return feedbackEnabled2 && userInfo2 !== null;
     }
-    const [qaEnabled, testerInfo, userInfo] = await Promise.all([
+    const [qaEnabled, feedbackEnabled, testerInfo, userInfo] = await Promise.all([
       this.isQAEnabled(),
+      this.isFeedbackEnabled(),
       this.getTesterInfo(),
       this.getCurrentUserInfo()
     ]);
     if (qaEnabled && testerInfo && testerInfo.role !== "feedback") return true;
-    if (userInfo) return true;
+    if (feedbackEnabled && userInfo) return true;
     return false;
   }
   /**
    * 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'
+   * - 'auto' → QA tester with QA enabled → 'qa', feedback enabled → 'feedback', else 'qa'
    */
   async getEffectiveMode() {
     const mode = this.config.mode || "qa";
     if (mode === "qa") return "qa";
     if (mode === "feedback") return "feedback";
-    const [qaEnabled, testerInfo] = await Promise.all([
+    const [qaEnabled, feedbackEnabled, testerInfo] = await Promise.all([
       this.isQAEnabled(),
+      this.isFeedbackEnabled(),
       this.getTesterInfo()
     ]);
     if (qaEnabled && testerInfo && testerInfo.role !== "feedback") return "qa";
-    return "feedback";
+    if (feedbackEnabled) return "feedback";
+    return "qa";
   }
   /**
    * Auto-provision a feedback user record in the testers table.
@@ -2446,7 +2636,7 @@ var BugBearClient = class {
           insertData.attachments = safeAttachments;
         }
       }
-      const { error } = await this.supabase.from("discussion_messages").insert(insertData);
+      const { data: msgData, error } = await this.supabase.from("discussion_messages").insert(insertData).select("id").single();
       if (error) {
         if (this._queue && isNetworkError(error.message)) {
           await this._queue.enqueue("message", insertData);
@@ -2455,6 +2645,10 @@ var BugBearClient = class {
         console.error("BugBear: Failed to send message", formatPgError(error));
         return false;
       }
+      if (msgData?.id) {
+        this.notifyDashboard("message", { threadId, messageId: msgData.id }).catch(() => {
+        });
+      }
       await this.markThreadAsRead(threadId);
       return true;
     } catch (err) {
@@ -2580,6 +2774,7 @@ var BugBearClient = class {
       if (!session) {
         return { success: false, error: "Session created but could not be fetched" };
       }
+      await this.cacheSession(session);
       return { success: true, session };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -2603,6 +2798,7 @@ var BugBearClient = class {
         return { success: false, error: error.message };
       }
       const session = this.transformSession(data);
+      await this.cacheSession(null);
       return { success: true, session };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -2618,8 +2814,13 @@ var BugBearClient = class {
       const testerInfo = await this.getTesterInfo();
       if (!testerInfo) return null;
       const { data, error } = await this.supabase.from("qa_sessions").select("*").eq("project_id", this.config.projectId).eq("tester_id", testerInfo.id).eq("status", "active").order("started_at", { ascending: false }).limit(1).maybeSingle();
-      if (error || !data) return null;
-      return this.transformSession(data);
+      if (error || !data) {
+        await this.cacheSession(null);
+        return null;
+      }
+      const session = this.transformSession(data);
+      await this.cacheSession(session);
+      return session;
     } catch (err) {
       console.error("BugBear: Error fetching active session", err);
       return null;
@@ -2801,6 +3002,96 @@ var BugBearClient = class {
 function createBugBear(config) {
   return new BugBearClient(config);
 }
+
+// src/email-interceptor.ts
+function defaultExtract(args) {
+  const first = args[0];
+  if (!first || typeof first !== "object") {
+    throw new Error("BugBear email interceptor: first argument must be an object with { to, subject }");
+  }
+  const obj = first;
+  return {
+    to: obj.to,
+    from: obj.from,
+    subject: obj.subject,
+    html: obj.html,
+    text: obj.text,
+    templateId: obj.templateId
+  };
+}
+function normalizeToArray(to) {
+  if (Array.isArray(to)) return to;
+  return [to];
+}
+function createEmailInterceptor(client, options = { mode: "capture" }) {
+  const { mode, filterTo, redactRecipients } = options;
+  return {
+    wrap(sendFn, wrapOpts) {
+      const extract = wrapOpts?.extractPayload || defaultExtract;
+      const wrapped = async (...args) => {
+        let extracted;
+        try {
+          extracted = extract(args);
+        } catch {
+          return sendFn(...args);
+        }
+        const toArray = normalizeToArray(extracted.to);
+        if (filterTo && filterTo.length > 0) {
+          const matches = toArray.some(
+            (addr) => filterTo.includes(addr.toLowerCase())
+          );
+          if (!matches) {
+            return sendFn(...args);
+          }
+        }
+        const capturedTo = redactRecipients ? toArray.map(() => "[redacted]") : toArray;
+        if (mode === "intercept") {
+          client.captureEmail({
+            to: capturedTo,
+            from: extracted.from,
+            subject: extracted.subject,
+            html: extracted.html,
+            text: extracted.text,
+            templateId: extracted.templateId,
+            captureMode: "intercept",
+            wasDelivered: false
+          }).catch(() => {
+          });
+          return { success: true, intercepted: true };
+        }
+        try {
+          const result = await sendFn(...args);
+          client.captureEmail({
+            to: capturedTo,
+            from: extracted.from,
+            subject: extracted.subject,
+            html: extracted.html,
+            text: extracted.text,
+            templateId: extracted.templateId,
+            captureMode: "capture",
+            wasDelivered: true
+          }).catch(() => {
+          });
+          return result;
+        } catch (err) {
+          client.captureEmail({
+            to: capturedTo,
+            from: extracted.from,
+            subject: extracted.subject,
+            html: extracted.html,
+            text: extracted.text,
+            templateId: extracted.templateId,
+            captureMode: "capture",
+            wasDelivered: false
+          }).catch(() => {
+          });
+          throw err;
+        }
+      };
+      return wrapped;
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUG_CATEGORIES,
@@ -2819,6 +3110,7 @@ function createBugBear(config) {
   captureError,
   contextCapture,
   createBugBear,
+  createEmailInterceptor,
   generateFingerprint,
   isBugCategory,
   isNetworkError,

package/dist/index.mjs

@@ -857,6 +857,8 @@ var BugBearClient = class {
     this.reportSubmitInFlight = false;
     /** Offline queue — only created when config.offlineQueue.enabled is true. */
     this._queue = null;
+    /** Session cache storage — defaults to LocalStorageAdapter. */
+    this._sessionStorage = new LocalStorageAdapter();
     /** Active Realtime channel references for cleanup. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this.realtimeChannels = [];
@@ -939,6 +941,10 @@ var BugBearClient = class {
     this.initOfflineQueue();
     this.initMonitoring();
   }
+  /** Cache key scoped to the active project. */
+  get sessionCacheKey() {
+    return `bugbear_session_${this.config.projectId ?? "unknown"}`;
+  }
   /** Initialize offline queue if configured. Shared by both init paths. */
   initOfflineQueue() {
     if (this.config.offlineQueue?.enabled) {
@@ -1002,6 +1008,26 @@ var BugBearClient = class {
     await this.pendingInit;
     if (this.initError) throw this.initError;
   }
+  /**
+   * Fire-and-forget call to a dashboard notification endpoint.
+   * Only works when apiKey is configured (needed for API auth).
+   * Failures are silently ignored — notifications are best-effort.
+   */
+  async notifyDashboard(path, body) {
+    if (!this.config.apiKey) return;
+    try {
+      const baseUrl = (this.config.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, "");
+      await fetch(`${baseUrl}/api/v1/notifications/${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify(body)
+      });
+    } catch {
+    }
+  }
   // ── Offline Queue ─────────────────────────────────────────
   /**
    * Access the offline queue (if enabled).
@@ -1028,6 +1054,48 @@ var BugBearClient = class {
     }
     await this._queue.load();
   }
+  // ── Session Cache ──────────────────────────────────────────
+  /**
+   * Swap the session cache storage adapter (for React Native — pass AsyncStorage).
+   * Must be called before getCachedSession() for persistence across app kills.
+   * Web callers don't need this — LocalStorageAdapter is the default.
+   */
+  setSessionStorage(adapter) {
+    this._sessionStorage = adapter;
+  }
+  /**
+   * Cache the active QA session locally for instant restore on app restart.
+   * Pass null to clear the cache (e.g. after ending a session).
+   */
+  async cacheSession(session) {
+    try {
+      if (session) {
+        await this._sessionStorage.setItem(this.sessionCacheKey, JSON.stringify(session));
+      } else {
+        await this._sessionStorage.removeItem(this.sessionCacheKey);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Retrieve the cached QA session. Returns null if no cache, if stale (>24h),
+   * or if parsing fails. The DB fetch in initializeBugBear() is the source of truth.
+   */
+  async getCachedSession() {
+    try {
+      const raw = await this._sessionStorage.getItem(this.sessionCacheKey);
+      if (!raw) return null;
+      const session = JSON.parse(raw);
+      const age = Date.now() - new Date(session.startedAt).getTime();
+      if (age > 24 * 60 * 60 * 1e3) {
+        await this._sessionStorage.removeItem(this.sessionCacheKey);
+        return null;
+      }
+      return session;
+    } catch {
+      return null;
+    }
+  }
   registerQueueHandlers() {
     if (!this._queue) return;
     this._queue.registerHandler("report", async (payload) => {
@@ -1045,6 +1113,11 @@ var BugBearClient = class {
       if (error) return { success: false, error: error.message };
       return { success: true };
     });
+    this._queue.registerHandler("email_capture", async (payload) => {
+      const { error } = await this.supabase.from("email_captures").insert(payload).select("id").single();
+      if (error) return { success: false, error: error.message };
+      return { success: true };
+    });
   }
   // ── Realtime Subscriptions ─────────────────────────────────
   /** Whether realtime is enabled in config. */
@@ -1232,6 +1305,8 @@ var BugBearClient = class {
       if (this.config.onReportSubmitted) {
         this.config.onReportSubmitted(report);
       }
+      this.notifyDashboard("report", { reportId: data.id }).catch(() => {
+      });
       return { success: true, reportId: data.id };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -1244,6 +1319,44 @@ var BugBearClient = class {
       this.reportSubmitInFlight = false;
     }
   }
+  /**
+   * Capture an email for QA testing.
+   * Called by the email interceptor — not typically called directly.
+   */
+  async captureEmail(payload) {
+    try {
+      await this.ready();
+      if (!payload.subject || !payload.to || payload.to.length === 0) {
+        return { success: false, error: "subject and to are required" };
+      }
+      const record = {
+        project_id: this.config.projectId,
+        to_addresses: payload.to,
+        from_address: payload.from || null,
+        subject: payload.subject,
+        html_content: payload.html || null,
+        text_content: payload.text || null,
+        template_id: payload.templateId || null,
+        metadata: payload.metadata || {},
+        capture_mode: payload.captureMode,
+        was_delivered: payload.wasDelivered,
+        delivery_status: payload.wasDelivered ? "sent" : "pending"
+      };
+      const { data, error } = await this.supabase.from("email_captures").insert(record).select("id").single();
+      if (error) {
+        if (this._queue && isNetworkError(error.message)) {
+          await this._queue.enqueue("email_capture", record);
+          return { success: false, queued: true, error: "Queued \u2014 will send when online" };
+        }
+        console.error("BugBear: Failed to capture email", error.message);
+        return { success: false, error: error.message };
+      }
+      return { success: true, captureId: data.id };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return { success: false, error: message };
+    }
+  }
   /**
    * Get assigned tests for current user
    * First looks up the tester by email, then fetches their assignments
@@ -1865,6 +1978,32 @@ var BugBearClient = class {
       return [];
     }
   }
+  /**
+   * Reopen a done issue that the tester believes isn't actually fixed.
+   * Transitions the report from a done status back to 'confirmed'.
+   */
+  async reopenReport(reportId, reason) {
+    try {
+      const testerInfo = await this.getTesterInfo();
+      if (!testerInfo) return { success: false, error: "Not authenticated as tester" };
+      const { data, error } = await this.supabase.rpc("reopen_report", {
+        p_report_id: reportId,
+        p_tester_id: testerInfo.id,
+        p_reason: reason
+      });
+      if (error) {
+        console.error("BugBear: Failed to reopen report", formatPgError(error));
+        return { success: false, error: error.message };
+      }
+      if (!data?.success) {
+        return { success: false, error: data?.error || "Failed to reopen report" };
+      }
+      return { success: true };
+    } catch (err) {
+      console.error("BugBear: Error reopening report", err);
+      return { success: false, error: "Unexpected error" };
+    }
+  }
   /**
    * Basic email format validation (defense in depth)
    */
@@ -2057,12 +2196,56 @@ var BugBearClient = class {
       return true;
     }
   }
+  /**
+   * Fetch server-side widget config set by the project admin.
+   * Returns settings like color scheme override. Returns empty config on error.
+   */
+  async getWidgetConfig() {
+    try {
+      await this.ensureReady();
+      const { data, error } = await this.supabase.rpc("get_widget_config", {
+        p_project_id: this.config.projectId
+      });
+      if (error) {
+        console.warn("BugBear: Could not fetch widget config", error.message || error.code || "Unknown error");
+        return {};
+      }
+      return data ?? {};
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error fetching widget config";
+      console.error("BugBear: Error fetching widget config", err);
+      this.config.onError?.(err instanceof Error ? err : new Error(message), { projectId: this.config.projectId });
+      return {};
+    }
+  }
+  /**
+   * Check if feedback mode is enabled for this project.
+   * This is a master switch that admins can toggle in the dashboard.
+   */
+  async isFeedbackEnabled() {
+    try {
+      await this.ensureReady();
+      const { data, error } = await this.supabase.rpc("check_feedback_enabled", {
+        p_project_id: this.config.projectId
+      });
+      if (error) {
+        console.warn("BugBear: Could not check feedback status", error.message || error.code || "Unknown error");
+        return false;
+      }
+      return data ?? false;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error checking feedback status";
+      console.error("BugBear: Error checking feedback status", err);
+      this.config.onError?.(err instanceof Error ? err : new Error(message), { projectId: this.config.projectId });
+      return false;
+    }
+  }
   /**
    * 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
+   * - 'feedback': Feedback enabled AND user is authenticated
+   * - 'auto': QA tester (if QA enabled) OR authenticated user (if feedback enabled)
    */
   async shouldShowWidget() {
     const mode = this.config.mode || "qa";
@@ -2074,33 +2257,39 @@ var BugBearClient = class {
       return qaEnabled2 && tester;
     }
     if (mode === "feedback") {
-      const userInfo2 = await this.getCurrentUserInfo();
-      return userInfo2 !== null;
+      const [feedbackEnabled2, userInfo2] = await Promise.all([
+        this.isFeedbackEnabled(),
+        this.getCurrentUserInfo()
+      ]);
+      return feedbackEnabled2 && userInfo2 !== null;
     }
-    const [qaEnabled, testerInfo, userInfo] = await Promise.all([
+    const [qaEnabled, feedbackEnabled, testerInfo, userInfo] = await Promise.all([
       this.isQAEnabled(),
+      this.isFeedbackEnabled(),
       this.getTesterInfo(),
       this.getCurrentUserInfo()
     ]);
     if (qaEnabled && testerInfo && testerInfo.role !== "feedback") return true;
-    if (userInfo) return true;
+    if (feedbackEnabled && userInfo) return true;
     return false;
   }
   /**
    * 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'
+   * - 'auto' → QA tester with QA enabled → 'qa', feedback enabled → 'feedback', else 'qa'
    */
   async getEffectiveMode() {
     const mode = this.config.mode || "qa";
     if (mode === "qa") return "qa";
     if (mode === "feedback") return "feedback";
-    const [qaEnabled, testerInfo] = await Promise.all([
+    const [qaEnabled, feedbackEnabled, testerInfo] = await Promise.all([
       this.isQAEnabled(),
+      this.isFeedbackEnabled(),
       this.getTesterInfo()
     ]);
     if (qaEnabled && testerInfo && testerInfo.role !== "feedback") return "qa";
-    return "feedback";
+    if (feedbackEnabled) return "feedback";
+    return "qa";
   }
   /**
    * Auto-provision a feedback user record in the testers table.
@@ -2401,7 +2590,7 @@ var BugBearClient = class {
           insertData.attachments = safeAttachments;
         }
       }
-      const { error } = await this.supabase.from("discussion_messages").insert(insertData);
+      const { data: msgData, error } = await this.supabase.from("discussion_messages").insert(insertData).select("id").single();
       if (error) {
         if (this._queue && isNetworkError(error.message)) {
           await this._queue.enqueue("message", insertData);
@@ -2410,6 +2599,10 @@ var BugBearClient = class {
         console.error("BugBear: Failed to send message", formatPgError(error));
         return false;
       }
+      if (msgData?.id) {
+        this.notifyDashboard("message", { threadId, messageId: msgData.id }).catch(() => {
+        });
+      }
       await this.markThreadAsRead(threadId);
       return true;
     } catch (err) {
@@ -2535,6 +2728,7 @@ var BugBearClient = class {
       if (!session) {
         return { success: false, error: "Session created but could not be fetched" };
       }
+      await this.cacheSession(session);
       return { success: true, session };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -2558,6 +2752,7 @@ var BugBearClient = class {
         return { success: false, error: error.message };
       }
       const session = this.transformSession(data);
+      await this.cacheSession(null);
       return { success: true, session };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -2573,8 +2768,13 @@ var BugBearClient = class {
       const testerInfo = await this.getTesterInfo();
       if (!testerInfo) return null;
       const { data, error } = await this.supabase.from("qa_sessions").select("*").eq("project_id", this.config.projectId).eq("tester_id", testerInfo.id).eq("status", "active").order("started_at", { ascending: false }).limit(1).maybeSingle();
-      if (error || !data) return null;
-      return this.transformSession(data);
+      if (error || !data) {
+        await this.cacheSession(null);
+        return null;
+      }
+      const session = this.transformSession(data);
+      await this.cacheSession(session);
+      return session;
     } catch (err) {
       console.error("BugBear: Error fetching active session", err);
       return null;
@@ -2756,6 +2956,96 @@ var BugBearClient = class {
 function createBugBear(config) {
   return new BugBearClient(config);
 }
+
+// src/email-interceptor.ts
+function defaultExtract(args) {
+  const first = args[0];
+  if (!first || typeof first !== "object") {
+    throw new Error("BugBear email interceptor: first argument must be an object with { to, subject }");
+  }
+  const obj = first;
+  return {
+    to: obj.to,
+    from: obj.from,
+    subject: obj.subject,
+    html: obj.html,
+    text: obj.text,
+    templateId: obj.templateId
+  };
+}
+function normalizeToArray(to) {
+  if (Array.isArray(to)) return to;
+  return [to];
+}
+function createEmailInterceptor(client, options = { mode: "capture" }) {
+  const { mode, filterTo, redactRecipients } = options;
+  return {
+    wrap(sendFn, wrapOpts) {
+      const extract = wrapOpts?.extractPayload || defaultExtract;
+      const wrapped = async (...args) => {
+        let extracted;
+        try {
+          extracted = extract(args);
+        } catch {
+          return sendFn(...args);
+        }
+        const toArray = normalizeToArray(extracted.to);
+        if (filterTo && filterTo.length > 0) {
+          const matches = toArray.some(
+            (addr) => filterTo.includes(addr.toLowerCase())
+          );
+          if (!matches) {
+            return sendFn(...args);
+          }
+        }
+        const capturedTo = redactRecipients ? toArray.map(() => "[redacted]") : toArray;
+        if (mode === "intercept") {
+          client.captureEmail({
+            to: capturedTo,
+            from: extracted.from,
+            subject: extracted.subject,
+            html: extracted.html,
+            text: extracted.text,
+            templateId: extracted.templateId,
+            captureMode: "intercept",
+            wasDelivered: false
+          }).catch(() => {
+          });
+          return { success: true, intercepted: true };
+        }
+        try {
+          const result = await sendFn(...args);
+          client.captureEmail({
+            to: capturedTo,
+            from: extracted.from,
+            subject: extracted.subject,
+            html: extracted.html,
+            text: extracted.text,
+            templateId: extracted.templateId,
+            captureMode: "capture",
+            wasDelivered: true
+          }).catch(() => {
+          });
+          return result;
+        } catch (err) {
+          client.captureEmail({
+            to: capturedTo,
+            from: extracted.from,
+            subject: extracted.subject,
+            html: extracted.html,
+            text: extracted.text,
+            templateId: extracted.templateId,
+            captureMode: "capture",
+            wasDelivered: false
+          }).catch(() => {
+          });
+          throw err;
+        }
+      };
+      return wrapped;
+    }
+  };
+}
 export {
   BUG_CATEGORIES,
   BugBearClient,
@@ -2773,6 +3063,7 @@ export {
   captureError,
   contextCapture,
   createBugBear,
+  createEmailInterceptor,
   generateFingerprint,
   isBugCategory,
   isNetworkError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bbearai/core",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Core utilities and types for BugBear QA platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",