@bbearai/core

Core client and utilities for BugBear QA platform.

Note: Most users should install @bbearai/react or @bbearai/react-native instead, which include this package automatically.

Installation

npm install @bbearai/core

Usage

import { createBugBear } from '@bbearai/core';

const bugbear = createBugBear({
  projectId: 'your-project-id',
  getCurrentUser: async () => ({
    id: 'user-123',
    email: '[email protected]',
    name: 'Jane Doe', // Optional, used for reporter identity
  }),
});

// Submit a report
await bugbear.submitReport({
  type: 'bug',
  description: 'Button does not work',
  severity: 'high',
  appContext: { currentRoute: '/dashboard' },
});

// Check if user is a tester
const isTester = await bugbear.isTester();

// Get assigned test cases
const assignments = await bugbear.getAssignedTests();

Configuration

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:

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.

What's captured automatically:

| 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:

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 | |--------|-------------| | 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 | | 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 | | getIssueCounts() | Get issue counts by category (open, done, reopened) | | getIssues(category) | Get enriched issue list with verification proof and original bug context | | uploadScreenshot(file) | Upload a screenshot |

Types

interface BugBearReport {
  type: 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
  description: string;
  title?: string;
  severity?: 'critical' | 'high' | 'medium' | 'low';
  screenshots?: string[];
  appContext?: AppContext;
  enhancedContext?: EnhancedBugContext;
}

interface AppContext {
  currentRoute: string;
  screenName?: string;
  userRole?: string;
  propertyId?: string;
  custom?: Record<string, unknown>;
}

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;
  };
}

type IssueCategory = 'open' | 'done' | 'reopened';

interface IssueCounts {
  open: number;
  done: number;
  reopened: number;
}

interface TesterIssue {
  id: string;
  title: string;
  description: string;
  reportType: ReportType;
  severity: Severity | null;
  status: ReportStatus;
  screenshotUrls: string[];
  route?: string;
  reporterName?: string;
  createdAt: string;
  updatedAt: string;
  verifiedByName?: string;   // Who retested (done issues)
  verifiedAt?: string;       // When verification passed (done issues)
  originalBugId?: string;    // Original report ID (reopened issues)
  originalBugTitle?: string; // Original bug title (reopened issues)
}

Issue Tracking

The SDK provides methods for testers to track their bug lifecycle:

// Get counts for issue cards (open, done, reopened)
const counts = await bugbear.getIssueCounts();
// { open: 3, done: 12, reopened: 1 }

// Get enriched issue list by category
const openIssues = await bugbear.getIssues('open');
const doneIssues = await bugbear.getIssues('done');
const reopenedIssues = await bugbear.getIssues('reopened');

// Done issues include verification proof
doneIssues[0].verifiedByName;  // "Jane Doe"
doneIssues[0].verifiedAt;      // "2026-02-05T12:00:00Z"

// Reopened issues include original bug context
reopenedIssues[0].originalBugTitle;  // "Login button unresponsive"
reopenedIssues[0].originalBugId;     // "uuid-of-original-report"

For Framework Authors

If you're building a BugBear integration for a different framework (Vue, Svelte, etc.), use this package as the foundation:

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);