@bbearai/core 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @bugbearai/core
+
+Core client and utilities for BugBear QA platform.
+
+> **Note:** Most users should install `@bugbearai/react` instead, which includes this package automatically.
+
+## Installation
+
+```bash
+npm install @bugbearai/core
+```
+
+## Usage
+
+```typescript
+import { createBugBear } from '@bugbearai/core';
+
+const bugbear = createBugBear({
+  projectId: 'your-project-id',
+  getCurrentUser: async () => ({
+    id: 'user-123',
+    email: 'user@example.com',
+  }),
+});
+
+// Submit a report
+await bugbear.submitReport({
+  type: 'bug',
+  description: 'Button does not work',
+  severity: 'high',
+});
+
+// Check if user is a tester
+const isTester = await bugbear.isTester();
+
+// Get assigned test cases
+const assignments = await bugbear.getAssignedTests();
+```
+
+## API Reference
+
+### createBugBear(config)
+
+Creates a BugBear client instance.
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `submitReport(report)` | Submit a bug report, feedback, or test result |
+| `isTester()` | Check if current user is a registered tester |
+| `isQAEnabled()` | Check if QA mode is enabled for the project |
+| `shouldShowWidget()` | Check if widget should be visible (QA enabled + is tester) |
+| `getTesterInfo()` | Get current tester's info |
+| `getAssignedTests()` | Get test cases assigned to current tester |
+| `trackNavigation(route)` | Track navigation for context |
+| `uploadScreenshot(file)` | Upload a screenshot |
+
+## Types
+
+```typescript
+interface BugBearReport {
+  type: 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
+  description: string;
+  title?: string;
+  severity?: 'critical' | 'high' | 'medium' | 'low';
+  screenshots?: string[];
+  appContext?: AppContext;
+  // ... and more
+}
+
+interface TesterInfo {
+  id: string;
+  name: string;
+  email: string;
+  assignedTests: number;
+  completedTests: number;
+}
+
+interface TestAssignment {
+  id: string;
+  status: string;
+  testCase: {
+    id: string;
+    title: string;
+    description: string;
+    steps: TestStep[];
+    expectedResult: string;
+    priority: string;
+  };
+}
+```
+
+## For Framework Authors
+
+If you're building a BugBear integration for a different framework (Vue, Svelte, etc.), use this package as the foundation:
+
+```typescript
+import { BugBearClient, createBugBear, BugBearConfig } from '@bugbearai/core';
+
+// Create your framework-specific wrapper around the client
+```

package/dist/index.d.mts

@@ -0,0 +1,434 @@
+/**
+ * BugBear Core Types
+ */
+type ReportType = 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+type ReportStatus = 'new' | 'triaging' | 'confirmed' | 'in_progress' | 'fixed' | 'verified' | 'wont_fix' | 'duplicate';
+interface AppContext {
+    /** Current route/screen path */
+    currentRoute: string;
+    /** Current screen name (human readable) */
+    screenName?: string;
+    /** Property ID if applicable */
+    propertyId?: string;
+    /** Property name if applicable */
+    propertyName?: string;
+    /** User's role in current context */
+    userRole?: string;
+    /** Any additional context the app wants to include */
+    custom?: Record<string, unknown>;
+    /** Component stack trace (for React errors) */
+    componentStack?: string;
+    /** Error message if an error occurred */
+    errorMessage?: string;
+    /** Error stack trace */
+    errorStack?: string;
+}
+/** Captured console log entry */
+interface ConsoleLogEntry {
+    level: 'log' | 'warn' | 'error' | 'info' | 'debug';
+    message: string;
+    timestamp: string;
+    args?: string[];
+}
+/** Captured network request */
+interface NetworkRequest {
+    method: string;
+    url: string;
+    status?: number;
+    duration?: number;
+    timestamp: string;
+    error?: string;
+}
+/** Enhanced bug context for detailed debugging */
+interface EnhancedBugContext {
+    /** Recent console logs (last 50) */
+    consoleLogs?: ConsoleLogEntry[];
+    /** Recent network requests (last 20) */
+    networkRequests?: NetworkRequest[];
+    /** Current Redux/state snapshot (serialized) */
+    stateSnapshot?: Record<string, unknown>;
+    /** Performance metrics */
+    performanceMetrics?: {
+        pageLoadTime?: number;
+        memoryUsage?: number;
+        fps?: number;
+    };
+    /** Browser/environment info */
+    environment?: {
+        language?: string;
+        timezone?: string;
+        cookiesEnabled?: boolean;
+        localStorage?: boolean;
+        online?: boolean;
+    };
+}
+interface DeviceInfo {
+    /** Platform: ios, android, web */
+    platform: 'ios' | 'android' | 'web';
+    /** OS version */
+    osVersion?: string;
+    /** App version */
+    appVersion?: string;
+    /** Device model */
+    deviceModel?: string;
+    /** Screen dimensions */
+    screenSize?: {
+        width: number;
+        height: number;
+    };
+    /** User agent (web) */
+    userAgent?: string;
+}
+interface BugBearReport {
+    /** Report type */
+    type: ReportType;
+    /** Description of the issue/feedback */
+    description: string;
+    /** Short title (can be auto-generated) */
+    title?: string;
+    /** Severity (for bugs) */
+    severity?: Severity;
+    /** Which step failed (for test failures) */
+    failedAtStep?: string;
+    /** Voice audio URL if voice input was used */
+    voiceAudioUrl?: string;
+    /** Transcribed voice text */
+    voiceTranscript?: string;
+    /** Screenshot URLs */
+    screenshots?: string[];
+    /** App context at time of report */
+    appContext: AppContext;
+    /** Device information */
+    deviceInfo: DeviceInfo;
+    /** Navigation history (last N screens) */
+    navigationHistory?: string[];
+    /** Linked test assignment ID (if testing assigned test) */
+    assignmentId?: string;
+    /** Linked test case ID */
+    testCaseId?: string;
+    /** Enhanced debugging context */
+    enhancedContext?: EnhancedBugContext;
+}
+/** User info from the host application */
+interface HostUserInfo {
+    /** User ID from the host app's auth system */
+    id: string;
+    /** User's email address */
+    email: string;
+}
+interface BugBearConfig {
+    /** Your BugBear project ID */
+    projectId: string;
+    /** Supabase URL (uses BugBear's hosted if not provided) */
+    supabaseUrl?: string;
+    /** Supabase anon key */
+    supabaseAnonKey?: string;
+    /** Enable voice input */
+    enableVoice?: boolean;
+    /** Enable screenshot capture */
+    enableScreenshots?: boolean;
+    /** Custom theme */
+    theme?: BugBearTheme;
+    /** Callback when report is submitted */
+    onReportSubmitted?: (report: BugBearReport) => void;
+    /** Function to get current app context */
+    getAppContext?: () => AppContext;
+    /** Function to get navigation history */
+    getNavigationHistory?: () => string[];
+    /**
+     * Function to get the current user from the host app's auth system.
+     * This is required when the host app uses a different Supabase instance.
+     * Returns null if no user is logged in.
+     */
+    getCurrentUser?: () => Promise<HostUserInfo | null>;
+    /**
+     * Callback to navigate to a specific route/screen.
+     * Used for deep linking from test cases to the screen being tested.
+     * @param route - The route path (web) or screen name (React Native)
+     */
+    onNavigate?: (route: string) => void;
+}
+interface BugBearTheme {
+    /** Primary brand color */
+    primaryColor?: string;
+    /** Background color for the widget */
+    backgroundColor?: string;
+    /** Text color */
+    textColor?: string;
+    /** Border radius */
+    borderRadius?: number;
+}
+type TestTemplate = 'steps' | 'checklist' | 'rubric' | 'freeform';
+type RubricMode = 'pass_fail' | 'rating';
+interface QATrack {
+    id: string;
+    name: string;
+    icon: string;
+    color: string;
+    testTemplate: TestTemplate;
+    /** For rubric/checklist: pass_fail shows checkboxes, rating shows 1-5 scale */
+    rubricMode?: RubricMode;
+    description?: string;
+}
+interface TestAssignment {
+    id: string;
+    testCase: {
+        id: string;
+        title: string;
+        testKey: string;
+        description?: string;
+        steps: TestStep[];
+        expectedResult: string;
+        priority: string;
+        /** Route/screen to navigate to when starting this test */
+        targetRoute?: string;
+        track?: QATrack;
+    };
+    status: 'pending' | 'in_progress' | 'passed' | 'failed' | 'blocked';
+}
+interface TestStep {
+    stepNumber: number;
+    action: string;
+    expectedResult?: string;
+}
+/** Result data for different template types */
+interface ChecklistResult {
+    itemIndex: number;
+    passed: boolean;
+    note?: string;
+}
+interface RubricResult {
+    criterionIndex: number;
+    rating: 1 | 2 | 3 | 4 | 5;
+    note?: string;
+}
+interface TestResult {
+    /** For checklist template */
+    checklistResults?: ChecklistResult[];
+    /** For rubric template */
+    rubricResults?: RubricResult[];
+    /** For freeform template */
+    freeformObservations?: string;
+    /** Overall notes */
+    notes?: string;
+}
+interface TesterInfo {
+    id: string;
+    name: string;
+    email: string;
+    assignedTests: number;
+    completedTests: number;
+}
+type ThreadType = 'announcement' | 'direct' | 'report' | 'general_note';
+type ThreadPriority = 'low' | 'normal' | 'high' | 'urgent';
+type MessageSenderType = 'admin' | 'tester';
+interface TesterThread {
+    id: string;
+    subject: string | null;
+    threadType: ThreadType;
+    priority: ThreadPriority;
+    isPinned: boolean;
+    isResolved: boolean;
+    lastMessageAt: string;
+    createdAt: string;
+    unreadCount: number;
+    lastMessage?: TesterMessage;
+}
+interface TesterMessage {
+    id: string;
+    threadId: string;
+    senderType: MessageSenderType;
+    senderName: string;
+    content: string;
+    createdAt: string;
+    attachments: Array<{
+        type: 'image' | 'document' | 'video_link';
+        url: string;
+        name: string;
+    }>;
+}
+
+/**
+ * BugBear Client
+ * Handles communication with the BugBear backend
+ */
+
+declare class BugBearClient {
+    private supabase;
+    private config;
+    private navigationHistory;
+    constructor(config: BugBearConfig);
+    /**
+     * Track navigation for context
+     */
+    trackNavigation(route: string): void;
+    /**
+     * Get current navigation history
+     */
+    getNavigationHistory(): string[];
+    /**
+     * Get current user info from host app or BugBear's own auth
+     */
+    private getCurrentUserInfo;
+    /**
+     * Submit a report
+     */
+    submitReport(report: Omit<BugBearReport, 'deviceInfo' | 'navigationHistory'> & {
+        deviceInfo?: DeviceInfo;
+    }): Promise<{
+        success: boolean;
+        reportId?: string;
+        error?: string;
+    }>;
+    /**
+     * Get assigned tests for current user
+     * First looks up the tester by email, then fetches their assignments
+     */
+    getAssignedTests(): Promise<TestAssignment[]>;
+    /**
+     * Get current tester info
+     * Looks up tester by email from the host app's authenticated user
+     */
+    getTesterInfo(): Promise<TesterInfo | null>;
+    /**
+     * Check if current user is a tester for this project
+     */
+    isTester(): Promise<boolean>;
+    /**
+     * Check if QA mode is enabled for this project
+     * This is a master switch that admins can toggle in the dashboard
+     */
+    isQAEnabled(): Promise<boolean>;
+    /**
+     * Check if the widget should be visible
+     * (QA mode enabled AND current user is a tester)
+     */
+    shouldShowWidget(): Promise<boolean>;
+    /**
+     * Upload a screenshot
+     */
+    uploadScreenshot(file: File | Blob, filename?: string): Promise<string | null>;
+    /**
+     * Generate a title from the report content
+     */
+    private generateTitle;
+    /**
+     * Get device info (override in platform-specific implementations)
+     */
+    private getDeviceInfo;
+    /**
+     * Create a fix request for Claude Code to pick up
+     * Called from the dashboard when user clicks "Send to Claude Code"
+     */
+    createFixRequest(request: {
+        title: string;
+        description?: string;
+        prompt: string;
+        filePath?: string;
+        reportId?: string;
+    }): Promise<{
+        success: boolean;
+        fixRequestId?: string;
+        error?: string;
+    }>;
+    /**
+     * Get pending fix requests for this project
+     * Useful for dashboard to show queue status
+     */
+    getFixRequests(options?: {
+        status?: 'pending' | 'claimed' | 'completed' | 'cancelled';
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        title: string;
+        description: string | null;
+        status: string;
+        claimedBy: string | null;
+        claimedAt: string | null;
+        completedAt: string | null;
+        createdAt: string;
+    }>>;
+    /**
+     * Get threads visible to the current tester
+     * Includes threads where audience is 'all' or tester is in audience_tester_ids
+     */
+    getThreadsForTester(): Promise<TesterThread[]>;
+    /**
+     * Get all messages in a thread
+     */
+    getThreadMessages(threadId: string): Promise<TesterMessage[]>;
+    /**
+     * Send a message to a thread
+     */
+    sendMessage(threadId: string, content: string): Promise<boolean>;
+    /**
+     * Mark a thread as read
+     */
+    markThreadAsRead(threadId: string): Promise<void>;
+    /**
+     * Get total unread message count across all threads
+     */
+    getUnreadCount(): Promise<number>;
+}
+/**
+ * Create a BugBear client instance
+ */
+declare function createBugBear(config: BugBearConfig): BugBearClient;
+
+/**
+ * BugBear Context Capture
+ * Utilities for capturing enhanced debugging context
+ */
+
+/**
+ * Context capture singleton that captures console logs and network requests
+ */
+declare class ContextCaptureManager {
+    private consoleLogs;
+    private networkRequests;
+    private originalConsole;
+    private originalFetch?;
+    private isCapturing;
+    /**
+     * Start capturing console logs and network requests
+     */
+    startCapture(): void;
+    /**
+     * Stop capturing and restore original functions
+     */
+    stopCapture(): void;
+    /**
+     * Get captured context for a bug report
+     */
+    getEnhancedContext(): EnhancedBugContext;
+    /**
+     * Clear captured data
+     */
+    clear(): void;
+    /**
+     * Add a log entry manually (for custom logging)
+     */
+    addLog(level: ConsoleLogEntry['level'], message: string, args?: string[]): void;
+    /**
+     * Add a network request manually
+     */
+    addNetworkRequest(request: NetworkRequest): void;
+    private captureConsole;
+    private captureFetch;
+    private getPerformanceMetrics;
+    private getEnvironmentInfo;
+}
+declare const contextCapture: ContextCaptureManager;
+/**
+ * Create an error boundary handler that captures React errors
+ */
+declare function captureError(error: Error, errorInfo?: {
+    componentStack?: string;
+}): {
+    errorMessage: string;
+    errorStack?: string;
+    componentStack?: string;
+};
+
+export { type AppContext, BugBearClient, type BugBearConfig, type BugBearReport, type BugBearTheme, type ChecklistResult, type ConsoleLogEntry, type DeviceInfo, type EnhancedBugContext, type HostUserInfo, type MessageSenderType, type NetworkRequest, type QATrack, type ReportStatus, type ReportType, type RubricMode, type RubricResult, type Severity, type TestAssignment, type TestResult, type TestStep, type TestTemplate, type TesterInfo, type TesterMessage, type TesterThread, type ThreadPriority, type ThreadType, captureError, contextCapture, createBugBear };