@bbearai/core 0.7.1 → 0.8.0

package/dist/index.d.mts

@@ -479,6 +479,7 @@ interface TesterThread {
     createdAt: string;
     unreadCount: number;
     lastMessage?: TesterMessage;
+    reporterName?: string;
 }
 interface TesterMessage {
     id: string;
@@ -789,6 +790,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
@@ -815,7 +860,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;
@@ -1042,6 +1087,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. */
@@ -1056,6 +1103,12 @@ declare class BugBearClient {
     private initialized;
     /** Initialization error, if any. */
     private initError;
+    /** Active presence session ID (passive time tracking). */
+    private _presenceSessionId;
+    /** Heartbeat interval for presence tracking. */
+    private _presenceInterval;
+    /** Whether presence is paused (tab hidden / app backgrounded). */
+    private _presencePaused;
     constructor(config: BugBearConfig);
     /** Whether the client is ready for requests. */
     get isReady(): boolean;
@@ -1068,6 +1121,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. */
@@ -1080,6 +1135,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.
@@ -1091,6 +1152,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;
@@ -1137,6 +1214,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
@@ -1253,6 +1335,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)
      */
@@ -1478,6 +1568,22 @@ declare class BugBearClient {
      * Transform database finding to QAFinding type
      */
     private transformFinding;
+    /** Current presence session ID (null if not tracking). */
+    get presenceSessionId(): string | null;
+    /**
+     * Start passive presence tracking for this tester.
+     * Idempotent — reuses an existing active session if one exists.
+     */
+    startPresence(platform: 'web' | 'ios' | 'android'): Promise<string | null>;
+    /** Gracefully end the current presence session. */
+    endPresence(): Promise<void>;
+    /** Pause heartbeat (tab hidden / app backgrounded). Sends one final beat. */
+    pausePresence(): void;
+    /** Resume heartbeat after pause. Restarts if session was cleaned up. */
+    resumePresence(): Promise<void>;
+    private heartbeatPresence;
+    private startPresenceHeartbeat;
+    private stopPresenceHeartbeat;
 }
 /**
  * Create a BugBear client instance
@@ -1558,4 +1664,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, type WidgetConfig, 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

@@ -479,6 +479,7 @@ interface TesterThread {
     createdAt: string;
     unreadCount: number;
     lastMessage?: TesterMessage;
+    reporterName?: string;
 }
 interface TesterMessage {
     id: string;
@@ -789,6 +790,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
@@ -815,7 +860,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;
@@ -1042,6 +1087,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. */
@@ -1056,6 +1103,12 @@ declare class BugBearClient {
     private initialized;
     /** Initialization error, if any. */
     private initError;
+    /** Active presence session ID (passive time tracking). */
+    private _presenceSessionId;
+    /** Heartbeat interval for presence tracking. */
+    private _presenceInterval;
+    /** Whether presence is paused (tab hidden / app backgrounded). */
+    private _presencePaused;
     constructor(config: BugBearConfig);
     /** Whether the client is ready for requests. */
     get isReady(): boolean;
@@ -1068,6 +1121,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. */
@@ -1080,6 +1135,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.
@@ -1091,6 +1152,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;
@@ -1137,6 +1214,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
@@ -1253,6 +1335,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)
      */
@@ -1478,6 +1568,22 @@ declare class BugBearClient {
      * Transform database finding to QAFinding type
      */
     private transformFinding;
+    /** Current presence session ID (null if not tracking). */
+    get presenceSessionId(): string | null;
+    /**
+     * Start passive presence tracking for this tester.
+     * Idempotent — reuses an existing active session if one exists.
+     */
+    startPresence(platform: 'web' | 'ios' | 'android'): Promise<string | null>;
+    /** Gracefully end the current presence session. */
+    endPresence(): Promise<void>;
+    /** Pause heartbeat (tab hidden / app backgrounded). Sends one final beat. */
+    pausePresence(): void;
+    /** Resume heartbeat after pause. Restarts if session was cleaned up. */
+    resumePresence(): Promise<void>;
+    private heartbeatPresence;
+    private startPresenceHeartbeat;
+    private stopPresenceHeartbeat;
 }
 /**
  * Create a BugBear client instance
@@ -1558,4 +1664,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, type WidgetConfig, 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 = [];
@@ -911,6 +914,12 @@ var BugBearClient = class {
     this.initialized = false;
     /** Initialization error, if any. */
     this.initError = null;
+    /** Active presence session ID (passive time tracking). */
+    this._presenceSessionId = null;
+    /** Heartbeat interval for presence tracking. */
+    this._presenceInterval = null;
+    /** Whether presence is paused (tab hidden / app backgrounded). */
+    this._presencePaused = false;
     this.config = config;
     if (config.apiKey) {
       this.pendingInit = this.resolveFromApiKey(config.apiKey);
@@ -984,6 +993,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 +1060,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 +1106,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 +1165,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 +1357,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 +1371,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 +2030,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)
    */
@@ -2419,6 +2565,7 @@ var BugBearClient = class {
         lastMessageAt: row.last_message_at,
         createdAt: row.created_at,
         unreadCount: Number(row.unread_count) || 0,
+        reporterName: row.reporter_name || void 0,
         lastMessage: row.last_message_preview ? {
           id: "",
           threadId: row.thread_id,
@@ -2496,7 +2643,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);
@@ -2505,6 +2652,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) {
@@ -2630,6 +2781,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";
@@ -2653,6 +2805,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";
@@ -2668,8 +2821,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;
@@ -2847,10 +3005,187 @@ var BugBearClient = class {
       updatedAt: data.updated_at
     };
   }
+  // ─── Passive Presence Tracking ──────────────────────────────
+  /** Current presence session ID (null if not tracking). */
+  get presenceSessionId() {
+    return this._presenceSessionId;
+  }
+  /**
+   * Start passive presence tracking for this tester.
+   * Idempotent — reuses an existing active session if one exists.
+   */
+  async startPresence(platform) {
+    try {
+      await this.ensureReady();
+      const testerInfo = await this.getTesterInfo();
+      if (!testerInfo) return null;
+      const { data, error } = await this.supabase.rpc("upsert_tester_presence", {
+        p_project_id: this.config.projectId,
+        p_tester_id: testerInfo.id,
+        p_platform: platform
+      });
+      if (error) {
+        console.error("BugBear: Failed to start presence", formatPgError(error));
+        return null;
+      }
+      this._presenceSessionId = data;
+      this._presencePaused = false;
+      this.startPresenceHeartbeat();
+      return data;
+    } catch (err) {
+      console.error("BugBear: Error starting presence", err);
+      return null;
+    }
+  }
+  /** Gracefully end the current presence session. */
+  async endPresence() {
+    this.stopPresenceHeartbeat();
+    if (!this._presenceSessionId) return;
+    try {
+      await this.supabase.rpc("end_tester_presence", {
+        p_session_id: this._presenceSessionId
+      });
+    } catch {
+    }
+    this._presenceSessionId = null;
+  }
+  /** Pause heartbeat (tab hidden / app backgrounded). Sends one final beat. */
+  pausePresence() {
+    this._presencePaused = true;
+    this.heartbeatPresence();
+  }
+  /** Resume heartbeat after pause. Restarts if session was cleaned up. */
+  async resumePresence() {
+    if (!this._presenceSessionId) return;
+    this._presencePaused = false;
+    try {
+      const { data } = await this.supabase.rpc("heartbeat_tester_presence", {
+        p_session_id: this._presenceSessionId
+      });
+      if (!data) {
+        this._presenceSessionId = null;
+      }
+    } catch {
+      this._presenceSessionId = null;
+    }
+  }
+  async heartbeatPresence() {
+    if (!this._presenceSessionId || this._presencePaused) return;
+    try {
+      const { data, error } = await this.supabase.rpc("heartbeat_tester_presence", {
+        p_session_id: this._presenceSessionId
+      });
+      if (error || data === false) {
+        this.stopPresenceHeartbeat();
+        this._presenceSessionId = null;
+      }
+    } catch {
+    }
+  }
+  startPresenceHeartbeat() {
+    this.stopPresenceHeartbeat();
+    this._presenceInterval = setInterval(() => this.heartbeatPresence(), 6e4);
+  }
+  stopPresenceHeartbeat() {
+    if (this._presenceInterval) {
+      clearInterval(this._presenceInterval);
+      this._presenceInterval = null;
+    }
+  }
 };
 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,
@@ -2869,6 +3204,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 = [];
@@ -866,6 +868,12 @@ var BugBearClient = class {
     this.initialized = false;
     /** Initialization error, if any. */
     this.initError = null;
+    /** Active presence session ID (passive time tracking). */
+    this._presenceSessionId = null;
+    /** Heartbeat interval for presence tracking. */
+    this._presenceInterval = null;
+    /** Whether presence is paused (tab hidden / app backgrounded). */
+    this._presencePaused = false;
     this.config = config;
     if (config.apiKey) {
       this.pendingInit = this.resolveFromApiKey(config.apiKey);
@@ -939,6 +947,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 +1014,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 +1060,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 +1119,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 +1311,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 +1325,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 +1984,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)
    */
@@ -2374,6 +2519,7 @@ var BugBearClient = class {
         lastMessageAt: row.last_message_at,
         createdAt: row.created_at,
         unreadCount: Number(row.unread_count) || 0,
+        reporterName: row.reporter_name || void 0,
         lastMessage: row.last_message_preview ? {
           id: "",
           threadId: row.thread_id,
@@ -2451,7 +2597,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);
@@ -2460,6 +2606,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) {
@@ -2585,6 +2735,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";
@@ -2608,6 +2759,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";
@@ -2623,8 +2775,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;
@@ -2802,10 +2959,187 @@ var BugBearClient = class {
       updatedAt: data.updated_at
     };
   }
+  // ─── Passive Presence Tracking ──────────────────────────────
+  /** Current presence session ID (null if not tracking). */
+  get presenceSessionId() {
+    return this._presenceSessionId;
+  }
+  /**
+   * Start passive presence tracking for this tester.
+   * Idempotent — reuses an existing active session if one exists.
+   */
+  async startPresence(platform) {
+    try {
+      await this.ensureReady();
+      const testerInfo = await this.getTesterInfo();
+      if (!testerInfo) return null;
+      const { data, error } = await this.supabase.rpc("upsert_tester_presence", {
+        p_project_id: this.config.projectId,
+        p_tester_id: testerInfo.id,
+        p_platform: platform
+      });
+      if (error) {
+        console.error("BugBear: Failed to start presence", formatPgError(error));
+        return null;
+      }
+      this._presenceSessionId = data;
+      this._presencePaused = false;
+      this.startPresenceHeartbeat();
+      return data;
+    } catch (err) {
+      console.error("BugBear: Error starting presence", err);
+      return null;
+    }
+  }
+  /** Gracefully end the current presence session. */
+  async endPresence() {
+    this.stopPresenceHeartbeat();
+    if (!this._presenceSessionId) return;
+    try {
+      await this.supabase.rpc("end_tester_presence", {
+        p_session_id: this._presenceSessionId
+      });
+    } catch {
+    }
+    this._presenceSessionId = null;
+  }
+  /** Pause heartbeat (tab hidden / app backgrounded). Sends one final beat. */
+  pausePresence() {
+    this._presencePaused = true;
+    this.heartbeatPresence();
+  }
+  /** Resume heartbeat after pause. Restarts if session was cleaned up. */
+  async resumePresence() {
+    if (!this._presenceSessionId) return;
+    this._presencePaused = false;
+    try {
+      const { data } = await this.supabase.rpc("heartbeat_tester_presence", {
+        p_session_id: this._presenceSessionId
+      });
+      if (!data) {
+        this._presenceSessionId = null;
+      }
+    } catch {
+      this._presenceSessionId = null;
+    }
+  }
+  async heartbeatPresence() {
+    if (!this._presenceSessionId || this._presencePaused) return;
+    try {
+      const { data, error } = await this.supabase.rpc("heartbeat_tester_presence", {
+        p_session_id: this._presenceSessionId
+      });
+      if (error || data === false) {
+        this.stopPresenceHeartbeat();
+        this._presenceSessionId = null;
+      }
+    } catch {
+    }
+  }
+  startPresenceHeartbeat() {
+    this.stopPresenceHeartbeat();
+    this._presenceInterval = setInterval(() => this.heartbeatPresence(), 6e4);
+  }
+  stopPresenceHeartbeat() {
+    if (this._presenceInterval) {
+      clearInterval(this._presenceInterval);
+      this._presenceInterval = null;
+    }
+  }
 };
 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,
@@ -2823,6 +3157,7 @@ export {
   captureError,
   contextCapture,
   createBugBear,
+  createEmailInterceptor,
   generateFingerprint,
   isBugCategory,
   isNetworkError,

package/package.json

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