@bbearai/core 0.2.12 → 0.2.14

package/README.md

@@ -2,7 +2,7 @@
 
 Core client and utilities for BugBear QA platform.
 
-> **Note:** Most users should install `@bbearai/react` instead, which includes this package automatically.
+> **Note:** Most users should install `@bbearai/react` or `@bbearai/react-native` instead, which include this package automatically.
 
 ## Installation
 
@@ -20,6 +20,7 @@ const bugbear = createBugBear({
   getCurrentUser: async () => ({
     id: 'user-123',
     email: 'user@example.com',
+    name: 'Jane Doe', // Optional, used for reporter identity
   }),
 });
 
@@ -28,6 +29,7 @@ await bugbear.submitReport({
   type: 'bug',
   description: 'Button does not work',
   severity: 'high',
+  appContext: { currentRoute: '/dashboard' },
 });
 
 // Check if user is a tester
@@ -37,13 +39,84 @@ const isTester = await bugbear.isTester();
 const assignments = await bugbear.getAssignedTests();
 ```
 
-## API Reference
+## Configuration
 
-### createBugBear(config)
+```typescript
+interface BugBearConfig {
+  // Required
+  projectId: string;
+  getCurrentUser: () => Promise<{ id: string; email: string; name?: string } | null>;
+
+  // Optional — context
+  getAppContext?: () => AppContext;          // Rich app context (userRole, etc.)
+  getNavigationHistory?: () => string[];    // Custom navigation tracking
+
+  // Optional — callbacks
+  onReportSubmitted?: (report: BugBearReport) => void;
+  onNavigate?: (route: string) => void;     // Deep linking from test cases
+
+  // Optional — self-hosted
+  supabaseUrl?: string;
+  supabaseAnonKey?: string;
+}
+```
+
+### AppContext
+
+Provide `getAppContext` to attach rich context to every bug report. This helps the developer fixing the bug understand the user's state:
+
+```typescript
+const bugbear = createBugBear({
+  projectId: 'your-project-id',
+  getCurrentUser: async () => ({ id: user.id, email: user.email }),
+  getAppContext: () => ({
+    currentRoute: window.location.pathname,
+    userRole: currentUser?.role,       // e.g. 'owner', 'manager', 'guest'
+    propertyId: currentProperty?.id,   // App-specific context
+    custom: {                          // Any additional context
+      theme: 'dark',
+      locale: 'en-US',
+    },
+  }),
+});
+```
+
+## Automatic Context Capture
+
+BugBear automatically captures debugging context when initialized via `BugBearProvider` (React or React Native). No manual setup required.
 
-Creates a BugBear client instance.
+**What's captured automatically:**
 
-### Client Methods
+| Data | Details |
+|------|---------|
+| **Console logs** | Last 50 `console.log/warn/error/info` calls |
+| **Network requests** | Last 20 `fetch()` calls with method, URL, status, duration |
+| **Failed response bodies** | First 500 chars of response body for 4xx/5xx errors |
+| **Navigation history** | Last 20 route changes (via `pushState`/`replaceState`/`popstate`) |
+| **Performance metrics** | Page load time, memory usage (Chrome) |
+| **Environment** | Language, timezone, online status, cookies, localStorage |
+
+This data is attached to every bug report as `enhanced_context` and is available to the MCP server's `get_report_context` tool.
+
+### Manual Capture (framework authors)
+
+If you're not using `BugBearProvider`, start capture manually:
+
+```typescript
+import { contextCapture } from '@bbearai/core';
+
+// Start capturing (call once at app init)
+contextCapture.startCapture();
+
+// For React Native: manually track screen changes
+contextCapture.trackNavigation('/home');
+contextCapture.trackNavigation('/settings');
+
+// Get captured data (automatically included in submitReport)
+const context = contextCapture.getEnhancedContext();
+```
+
+## Client Methods
 
 | Method | Description |
 |--------|-------------|
@@ -53,7 +126,9 @@ Creates a BugBear client instance.
 | `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 |
+| `getAppContext()` | Get current app context (uses config callback or auto-captured) |
+| `getNavigationHistory()` | Get navigation history (config callback > manual > auto-captured) |
+| `trackNavigation(route)` | Manually track a route change |
 | `uploadScreenshot(file)` | Upload a screenshot |
 
 ## Types
@@ -66,7 +141,15 @@ interface BugBearReport {
   severity?: 'critical' | 'high' | 'medium' | 'low';
   screenshots?: string[];
   appContext?: AppContext;
-  // ... and more
+  enhancedContext?: EnhancedBugContext;
+}
+
+interface AppContext {
+  currentRoute: string;
+  screenName?: string;
+  userRole?: string;
+  propertyId?: string;
+  custom?: Record<string, unknown>;
 }
 
 interface TesterInfo {
@@ -96,7 +179,11 @@ interface TestAssignment {
 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 '@bbearai/core';
+import { BugBearClient, createBugBear, contextCapture, BugBearConfig } from '@bbearai/core';
+
+// Start context capture at app init
+contextCapture.startCapture();
 
 // Create your framework-specific wrapper around the client
+const client = createBugBear(config);
 ```

package/dist/index.d.mts

@@ -662,11 +662,30 @@ declare class BugBearClient {
         error?: string;
         durationSeconds?: number;
     }>;
+    /**
+     * Pass a test assignment — convenience wrapper around updateAssignmentStatus
+     */
+    passAssignment(assignmentId: string): Promise<{
+        success: boolean;
+        error?: string;
+        durationSeconds?: number;
+    }>;
+    /**
+     * Fail a test assignment — convenience wrapper around updateAssignmentStatus
+     */
+    failAssignment(assignmentId: string): Promise<{
+        success: boolean;
+        error?: string;
+        durationSeconds?: number;
+    }>;
     /**
      * Skip a test assignment with a required reason
      * Marks the assignment as 'skipped' and records why it was skipped
      */
-    skipAssignment(assignmentId: string, reason: SkipReason, notes?: string): Promise<{
+    skipAssignment(assignmentId: string, reason: SkipReason | {
+        reason: SkipReason;
+        notes?: string;
+    }, notes?: string): Promise<{
         success: boolean;
         error?: string;
     }>;

package/dist/index.d.ts

@@ -662,11 +662,30 @@ declare class BugBearClient {
         error?: string;
         durationSeconds?: number;
     }>;
+    /**
+     * Pass a test assignment — convenience wrapper around updateAssignmentStatus
+     */
+    passAssignment(assignmentId: string): Promise<{
+        success: boolean;
+        error?: string;
+        durationSeconds?: number;
+    }>;
+    /**
+     * Fail a test assignment — convenience wrapper around updateAssignmentStatus
+     */
+    failAssignment(assignmentId: string): Promise<{
+        success: boolean;
+        error?: string;
+        durationSeconds?: number;
+    }>;
     /**
      * Skip a test assignment with a required reason
      * Marks the assignment as 'skipped' and records why it was skipped
      */
-    skipAssignment(assignmentId: string, reason: SkipReason, notes?: string): Promise<{
+    skipAssignment(assignmentId: string, reason: SkipReason | {
+        reason: SkipReason;
+        notes?: string;
+    }, notes?: string): Promise<{
         success: boolean;
         error?: string;
     }>;

package/dist/index.js

@@ -630,19 +630,40 @@ var BugBearClient = class {
       return { success: false, error: message };
     }
   }
+  /**
+   * Pass a test assignment — convenience wrapper around updateAssignmentStatus
+   */
+  async passAssignment(assignmentId) {
+    return this.updateAssignmentStatus(assignmentId, "passed");
+  }
+  /**
+   * Fail a test assignment — convenience wrapper around updateAssignmentStatus
+   */
+  async failAssignment(assignmentId) {
+    return this.updateAssignmentStatus(assignmentId, "failed");
+  }
   /**
    * Skip a test assignment with a required reason
    * Marks the assignment as 'skipped' and records why it was skipped
    */
   async skipAssignment(assignmentId, reason, notes) {
+    let actualReason;
+    let actualNotes;
+    if (typeof reason === "object") {
+      actualReason = reason.reason;
+      actualNotes = reason.notes;
+    } else {
+      actualReason = reason;
+      actualNotes = notes;
+    }
     try {
       const updateData = {
         status: "skipped",
-        skip_reason: reason,
+        skip_reason: actualReason,
         completed_at: (/* @__PURE__ */ new Date()).toISOString()
       };
-      if (notes) {
-        updateData.notes = notes;
+      if (actualNotes) {
+        updateData.notes = actualNotes;
       }
       const { error } = await this.supabase.from("test_assignments").update(updateData).eq("id", assignmentId);
       if (error) {
@@ -1282,6 +1303,7 @@ var BugBearClient = class {
         return false;
       }
       await this.supabase.from("discussion_threads").update({ last_message_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", threadId);
+      await this.markThreadAsRead(threadId);
       return true;
     } catch (err) {
       console.error("BugBear: Error sending message", err);

package/dist/index.mjs

@@ -601,19 +601,40 @@ var BugBearClient = class {
       return { success: false, error: message };
     }
   }
+  /**
+   * Pass a test assignment — convenience wrapper around updateAssignmentStatus
+   */
+  async passAssignment(assignmentId) {
+    return this.updateAssignmentStatus(assignmentId, "passed");
+  }
+  /**
+   * Fail a test assignment — convenience wrapper around updateAssignmentStatus
+   */
+  async failAssignment(assignmentId) {
+    return this.updateAssignmentStatus(assignmentId, "failed");
+  }
   /**
    * Skip a test assignment with a required reason
    * Marks the assignment as 'skipped' and records why it was skipped
    */
   async skipAssignment(assignmentId, reason, notes) {
+    let actualReason;
+    let actualNotes;
+    if (typeof reason === "object") {
+      actualReason = reason.reason;
+      actualNotes = reason.notes;
+    } else {
+      actualReason = reason;
+      actualNotes = notes;
+    }
     try {
       const updateData = {
         status: "skipped",
-        skip_reason: reason,
+        skip_reason: actualReason,
         completed_at: (/* @__PURE__ */ new Date()).toISOString()
       };
-      if (notes) {
-        updateData.notes = notes;
+      if (actualNotes) {
+        updateData.notes = actualNotes;
       }
       const { error } = await this.supabase.from("test_assignments").update(updateData).eq("id", assignmentId);
       if (error) {
@@ -1253,6 +1274,7 @@ var BugBearClient = class {
         return false;
       }
       await this.supabase.from("discussion_threads").update({ last_message_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", threadId);
+      await this.markThreadAsRead(threadId);
       return true;
     } catch (err) {
       console.error("BugBear: Error sending message", err);

package/package.json

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