@bbearai/core 0.4.6 → 0.5.0

package/dist/index.d.mts

@@ -134,10 +134,10 @@ interface HostUserInfo {
 interface BugBearConfig {
     /** Your BugBear project ID */
     projectId: string;
-    /** Supabase URL (uses BugBear's hosted if not provided) */
-    supabaseUrl?: string;
-    /** Supabase anon key */
-    supabaseAnonKey?: string;
+    /** Supabase URL for the BugBear backend */
+    supabaseUrl: string;
+    /** Supabase anon key for the BugBear backend */
+    supabaseAnonKey: string;
     /** Enable voice input */
     enableVoice?: boolean;
     /** Enable screenshot capture */
@@ -173,6 +173,27 @@ interface BugBearConfig {
      * Wire this to your error reporting service (e.g. Sentry.captureException).
      */
     onError?: (error: Error, context?: Record<string, unknown>) => void;
+    /**
+     * Enable offline queue for network-resilient submissions.
+     * When a submitReport, sendMessage, or submitTestFeedback call fails
+     * due to a network error, the operation is stored locally and retried
+     * when connectivity returns.
+     */
+    offlineQueue?: {
+        enabled: boolean;
+        /** Maximum items to keep in the queue (oldest evicted first). Default 50. */
+        maxItems?: number;
+        /** Maximum retry attempts per item before it is dropped. Default 5. */
+        maxRetries?: number;
+    };
+    /**
+     * Enable Supabase Realtime subscriptions for instant updates.
+     * Subscribes to changes on test_assignments, discussion_messages, and reports.
+     * Falls back to polling if subscription fails.
+     */
+    realtime?: {
+        enabled: boolean;
+    };
 }
 interface BugBearTheme {
     /** Primary brand color */
@@ -650,6 +671,97 @@ interface TesterIssue {
     originalBugTitle?: string;
 }
 
+/**
+ * BugBear Offline Queue
+ *
+ * Persists failed network operations and retries them when connectivity returns.
+ * Uses a StorageAdapter interface so web (localStorage) and React Native
+ * (AsyncStorage) can each supply their own persistence layer.
+ */
+/** Platform-agnostic async storage interface. */
+interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Default adapter that wraps `window.localStorage`.
+ * Falls back to in-memory storage when localStorage is unavailable
+ * (e.g. SSR, workers, or storage quota exceeded).
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private fallback;
+    private get isAvailable();
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+type QueueItemType = 'report' | 'message' | 'feedback';
+interface QueueItem {
+    /** Unique ID for this queued operation. */
+    id: string;
+    /** Which client method to replay. */
+    type: QueueItemType;
+    /** Already-enriched payload ready for INSERT/RPC. */
+    payload: unknown;
+    /** Epoch ms when the item was queued. */
+    createdAt: number;
+    /** How many times flush has tried (and failed) to replay this item. */
+    retries: number;
+}
+interface OfflineQueueConfig {
+    enabled: boolean;
+    /** Maximum items to keep in the queue (oldest evicted first). Default 50. */
+    maxItems?: number;
+    /** Maximum retry attempts per item before it is dropped. Default 5. */
+    maxRetries?: number;
+    /** Platform-specific storage adapter. Default: LocalStorageAdapter. */
+    storage?: StorageAdapter;
+}
+type FlushHandler = (payload: unknown) => Promise<{
+    success: boolean;
+    error?: string;
+}>;
+declare class OfflineQueue {
+    private items;
+    private maxItems;
+    private maxRetries;
+    private storage;
+    private storageKey;
+    private flushing;
+    private handlers;
+    private listener?;
+    constructor(config: OfflineQueueConfig);
+    /** Register a handler that replays a queued operation. */
+    registerHandler(type: QueueItemType, handler: FlushHandler): void;
+    /** Subscribe to queue count changes (for UI badges). */
+    onChange(callback: (count: number) => void): void;
+    private notify;
+    /** Load queue from persistent storage. Call once after construction. */
+    load(): Promise<void>;
+    private save;
+    /** Add a failed operation to the queue. Returns the item ID. */
+    enqueue(type: QueueItemType, payload: unknown): Promise<string>;
+    /** Number of items waiting to be flushed. */
+    get count(): number;
+    /** Read-only snapshot of pending items. */
+    get pending(): readonly QueueItem[];
+    /** Whether a flush is currently in progress. */
+    get isFlushing(): boolean;
+    /**
+     * Process all queued items in FIFO order.
+     * Stops early if a network error is encountered (still offline).
+     */
+    flush(): Promise<{
+        flushed: number;
+        failed: number;
+    }>;
+    /** Drop all queued items. */
+    clear(): Promise<void>;
+}
+/** Heuristic: does this error string look like a connectivity failure? */
+declare function isNetworkError(error?: string | null): boolean;
+
 /**
  * BugBear Client
  * Handles communication with the BugBear backend
@@ -660,7 +772,38 @@ declare class BugBearClient {
     private config;
     private navigationHistory;
     private reportSubmitInFlight;
+    /** Offline queue — only created when config.offlineQueue.enabled is true. */
+    private _queue;
+    /** Active Realtime channel references for cleanup. */
+    private realtimeChannels;
     constructor(config: BugBearConfig);
+    /**
+     * Access the offline queue (if enabled).
+     * Use this to check queue.count, subscribe to changes, or trigger flush.
+     */
+    get queue(): OfflineQueue | null;
+    /**
+     * Initialize the offline queue with a platform-specific storage adapter.
+     * Must be called after construction for React Native (which supplies AsyncStorage).
+     * Web callers can skip this — LocalStorageAdapter is the default.
+     */
+    initQueue(storage?: StorageAdapter): Promise<void>;
+    private registerQueueHandlers;
+    /** Whether realtime is enabled in config. */
+    get realtimeEnabled(): boolean;
+    /**
+     * Subscribe to postgres_changes on relevant tables.
+     * Each callback fires when the corresponding table has changes —
+     * the provider should call its refresh function in response.
+     * Returns a cleanup function that unsubscribes all channels.
+     */
+    subscribeToChanges(callbacks: {
+        onAssignmentChange?: () => void;
+        onMessageChange?: () => void;
+        onReportChange?: () => void;
+    }): () => void;
+    /** Remove all active Realtime channels. */
+    unsubscribeAll(): void;
     /**
      * Track navigation for context.
      * Also forwards to contextCapture for auto-tracked navigation.
@@ -688,13 +831,17 @@ declare class BugBearClient {
     }): Promise<{
         success: boolean;
         reportId?: string;
+        queued?: boolean;
         error?: string;
     }>;
     /**
      * Get assigned tests for current user
      * First looks up the tester by email, then fetches their assignments
      */
-    getAssignedTests(): Promise<TestAssignment[]>;
+    getAssignedTests(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<TestAssignment[]>;
     /**
      * Get assignment by ID with time tracking fields
      */
@@ -751,6 +898,7 @@ declare class BugBearClient {
      */
     submitTestFeedback(options: SubmitFeedbackOptions): Promise<{
         success: boolean;
+        queued?: boolean;
         error?: string;
     }>;
     /**
@@ -1073,4 +1221,4 @@ declare function captureError(error: Error, errorInfo?: {
     componentStack?: string;
 };
 
-export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, type MessageSenderType, type NetworkRequest, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type RegressionEvent, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear, isBugCategory };
+export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, LocalStorageAdapter, type MessageSenderType, type NetworkRequest, OfflineQueue, type OfflineQueueConfig, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type QueueItem, type QueueItemType, type RegressionEvent, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type StorageAdapter, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear, isBugCategory, isNetworkError };

package/dist/index.d.ts

@@ -134,10 +134,10 @@ interface HostUserInfo {
 interface BugBearConfig {
     /** Your BugBear project ID */
     projectId: string;
-    /** Supabase URL (uses BugBear's hosted if not provided) */
-    supabaseUrl?: string;
-    /** Supabase anon key */
-    supabaseAnonKey?: string;
+    /** Supabase URL for the BugBear backend */
+    supabaseUrl: string;
+    /** Supabase anon key for the BugBear backend */
+    supabaseAnonKey: string;
     /** Enable voice input */
     enableVoice?: boolean;
     /** Enable screenshot capture */
@@ -173,6 +173,27 @@ interface BugBearConfig {
      * Wire this to your error reporting service (e.g. Sentry.captureException).
      */
     onError?: (error: Error, context?: Record<string, unknown>) => void;
+    /**
+     * Enable offline queue for network-resilient submissions.
+     * When a submitReport, sendMessage, or submitTestFeedback call fails
+     * due to a network error, the operation is stored locally and retried
+     * when connectivity returns.
+     */
+    offlineQueue?: {
+        enabled: boolean;
+        /** Maximum items to keep in the queue (oldest evicted first). Default 50. */
+        maxItems?: number;
+        /** Maximum retry attempts per item before it is dropped. Default 5. */
+        maxRetries?: number;
+    };
+    /**
+     * Enable Supabase Realtime subscriptions for instant updates.
+     * Subscribes to changes on test_assignments, discussion_messages, and reports.
+     * Falls back to polling if subscription fails.
+     */
+    realtime?: {
+        enabled: boolean;
+    };
 }
 interface BugBearTheme {
     /** Primary brand color */
@@ -650,6 +671,97 @@ interface TesterIssue {
     originalBugTitle?: string;
 }
 
+/**
+ * BugBear Offline Queue
+ *
+ * Persists failed network operations and retries them when connectivity returns.
+ * Uses a StorageAdapter interface so web (localStorage) and React Native
+ * (AsyncStorage) can each supply their own persistence layer.
+ */
+/** Platform-agnostic async storage interface. */
+interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Default adapter that wraps `window.localStorage`.
+ * Falls back to in-memory storage when localStorage is unavailable
+ * (e.g. SSR, workers, or storage quota exceeded).
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private fallback;
+    private get isAvailable();
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+type QueueItemType = 'report' | 'message' | 'feedback';
+interface QueueItem {
+    /** Unique ID for this queued operation. */
+    id: string;
+    /** Which client method to replay. */
+    type: QueueItemType;
+    /** Already-enriched payload ready for INSERT/RPC. */
+    payload: unknown;
+    /** Epoch ms when the item was queued. */
+    createdAt: number;
+    /** How many times flush has tried (and failed) to replay this item. */
+    retries: number;
+}
+interface OfflineQueueConfig {
+    enabled: boolean;
+    /** Maximum items to keep in the queue (oldest evicted first). Default 50. */
+    maxItems?: number;
+    /** Maximum retry attempts per item before it is dropped. Default 5. */
+    maxRetries?: number;
+    /** Platform-specific storage adapter. Default: LocalStorageAdapter. */
+    storage?: StorageAdapter;
+}
+type FlushHandler = (payload: unknown) => Promise<{
+    success: boolean;
+    error?: string;
+}>;
+declare class OfflineQueue {
+    private items;
+    private maxItems;
+    private maxRetries;
+    private storage;
+    private storageKey;
+    private flushing;
+    private handlers;
+    private listener?;
+    constructor(config: OfflineQueueConfig);
+    /** Register a handler that replays a queued operation. */
+    registerHandler(type: QueueItemType, handler: FlushHandler): void;
+    /** Subscribe to queue count changes (for UI badges). */
+    onChange(callback: (count: number) => void): void;
+    private notify;
+    /** Load queue from persistent storage. Call once after construction. */
+    load(): Promise<void>;
+    private save;
+    /** Add a failed operation to the queue. Returns the item ID. */
+    enqueue(type: QueueItemType, payload: unknown): Promise<string>;
+    /** Number of items waiting to be flushed. */
+    get count(): number;
+    /** Read-only snapshot of pending items. */
+    get pending(): readonly QueueItem[];
+    /** Whether a flush is currently in progress. */
+    get isFlushing(): boolean;
+    /**
+     * Process all queued items in FIFO order.
+     * Stops early if a network error is encountered (still offline).
+     */
+    flush(): Promise<{
+        flushed: number;
+        failed: number;
+    }>;
+    /** Drop all queued items. */
+    clear(): Promise<void>;
+}
+/** Heuristic: does this error string look like a connectivity failure? */
+declare function isNetworkError(error?: string | null): boolean;
+
 /**
  * BugBear Client
  * Handles communication with the BugBear backend
@@ -660,7 +772,38 @@ declare class BugBearClient {
     private config;
     private navigationHistory;
     private reportSubmitInFlight;
+    /** Offline queue — only created when config.offlineQueue.enabled is true. */
+    private _queue;
+    /** Active Realtime channel references for cleanup. */
+    private realtimeChannels;
     constructor(config: BugBearConfig);
+    /**
+     * Access the offline queue (if enabled).
+     * Use this to check queue.count, subscribe to changes, or trigger flush.
+     */
+    get queue(): OfflineQueue | null;
+    /**
+     * Initialize the offline queue with a platform-specific storage adapter.
+     * Must be called after construction for React Native (which supplies AsyncStorage).
+     * Web callers can skip this — LocalStorageAdapter is the default.
+     */
+    initQueue(storage?: StorageAdapter): Promise<void>;
+    private registerQueueHandlers;
+    /** Whether realtime is enabled in config. */
+    get realtimeEnabled(): boolean;
+    /**
+     * Subscribe to postgres_changes on relevant tables.
+     * Each callback fires when the corresponding table has changes —
+     * the provider should call its refresh function in response.
+     * Returns a cleanup function that unsubscribes all channels.
+     */
+    subscribeToChanges(callbacks: {
+        onAssignmentChange?: () => void;
+        onMessageChange?: () => void;
+        onReportChange?: () => void;
+    }): () => void;
+    /** Remove all active Realtime channels. */
+    unsubscribeAll(): void;
     /**
      * Track navigation for context.
      * Also forwards to contextCapture for auto-tracked navigation.
@@ -688,13 +831,17 @@ declare class BugBearClient {
     }): Promise<{
         success: boolean;
         reportId?: string;
+        queued?: boolean;
         error?: string;
     }>;
     /**
      * Get assigned tests for current user
      * First looks up the tester by email, then fetches their assignments
      */
-    getAssignedTests(): Promise<TestAssignment[]>;
+    getAssignedTests(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<TestAssignment[]>;
     /**
      * Get assignment by ID with time tracking fields
      */
@@ -751,6 +898,7 @@ declare class BugBearClient {
      */
     submitTestFeedback(options: SubmitFeedbackOptions): Promise<{
         success: boolean;
+        queued?: boolean;
         error?: string;
     }>;
     /**
@@ -1073,4 +1221,4 @@ declare function captureError(error: Error, errorInfo?: {
     componentStack?: string;
 };
 
-export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, type MessageSenderType, type NetworkRequest, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type RegressionEvent, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear, isBugCategory };
+export { type AddFindingOptions, type AppContext, BUG_CATEGORIES, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type BugCategory, type ChecklistItem, type ChecklistResult, type ConsoleLogEntry, type CoverageGap, type CoverageMatrixCell, type CoverageMatrixRow, type DeployChecklist, type DeviceInfo, type EndSessionOptions, type EnhancedBugContext, type FindingSeverity, type FindingType, type HostUserInfo, type IssueCategory, type IssueCounts, LocalStorageAdapter, type MessageSenderType, type NetworkRequest, OfflineQueue, type OfflineQueueConfig, type PriorityFactors, type ProjectRole, type QAFinding, type QAHealthMetrics, type QAHealthScore, type QASession, type QASessionStatus, type QATrack, type QueueItem, type QueueItemType, type RegressionEvent, type ReportStatus, type ReportType, type RoutePriority, type RouteTestStats, type RubricMode, type RubricResult, type Severity, type SkipReason, type StartSessionOptions, type StorageAdapter, type SubmitFeedbackOptions, type TestAssignment, type TestFeedback, type TestGroup, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterIssue, type TesterMessage, type TesterProfileUpdate, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear, isBugCategory, isNetworkError };