@bugmail-js/sdk — Browser JavaScript SDK

The BugMail browser SDK captures unhandled errors, unhandled promise rejections, and user breadcrumbs and sends them to your BugMail backend. Optional plugins add more features (e.g., performance metrics, network breadcrumbs).

This README provides a fast, friendly guide so users can get started quickly via npm or CDN and understand common integration points.

Installation

# Using npm
npm install @bugmail-js/sdk

# Using pnpm
pnpm add @bugmail-js/sdk

CDN

<!-- jsDelivr (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/@bugmail-js/[email protected]/dist/bugmail.umd.js"></script>
<!-- or unpkg -->
<script src="https://unpkg.com/@bugmail-js/[email protected]/dist/bugmail.umd.js"></script>

Quick start (browser)

// Option 1: Default import (recommended for compatibility with examples)
import BugMail from '@bugmail-js/sdk';
const bugmail = new BugMail({ 
  apiKey: 'YOUR_PROJECT_API_KEY',
  endpoint: '<your-bugmail-endpoint>'
});

// Option 2: Named import
import { BugMailClient } from '@bugmail-js/sdk';
const bugmail2 = new BugMailClient({ 
  apiKey: 'YOUR_PROJECT_API_KEY',
  endpoint: '<your-bugmail-endpoint>'
});

// Note on casing: the exported class is `BugMailClient` (camel-case). Import names are case-sensitive.

// API key is required. If not provided, the SDK will warn and will not auto-initialize.

// Optional: set user context
bugmail.setUser({ id: '123', email: '[email protected]' });

// Manual capture
try {
  throw new Error('Manual test');
} catch (err) {
  bugmail.captureError(err, { component: 'Checkout' });
}

Key API

• new BugMail(config) - initialize the SDK

  • apiKey (required) — project API key (sent as x-bugmail-api-key header)
  • endpoint — BugMail backend URL (e.g., <your-bugmail-endpoint>)
  • environment, release, sampleRate, maxBreadcrumbs

• captureError(error, context) — send an error manually

• setUser(user) — attach user metadata: { id, email, name }

• setContext(context) — attach custom context data

• addBreadcrumb(breadcrumb) — programmatically add breadcrumb

Framework integrations (quick)

Note: The React/Vue packages are experimental and may not yet be published to npm. The snippets below show intended usage once available. Until then, you can integrate the browser SDK directly in those frameworks.

React

import { BugMailProvider, ErrorBoundary } from '@bugmail-js/react';

function App() {
  return (
    <BugMailProvider apiKey="YOUR_API_KEY">
      <ErrorBoundary fallback={<div>Something broke</div>}>
        <YourApp />
      </ErrorBoundary>
    </BugMailProvider>
  );
}

Vue

import { createApp } from 'vue';
import { bugmailPlugin } from '@bugmail-js/vue';
import App from './App.vue';

const app = createApp(App);
app.use(bugmailPlugin, { apiKey: 'YOUR_API_KEY' });
app.mount('#app');

Examples

• See bugmail-sdk/examples/browser-demo for a runnable demo.
• Server-side ingestion examples use the Node SDK (@bugmail-js/node) in examples/express-server.

Troubleshooting

• If you see no reports: check apiKey, endpoint, and browser console for network errors.
• CSP: ensure your CSP allows requests to your BugMail API endpoint.

Contributing and tests

• This package builds from src/ and outputs dist/ via Rollup. Tests use Jest.

License

MIT

BugMail SDK

JavaScript error tracking SDK for the BugMail platform.

Features

• Automatic error capturing for unhandled exceptions
• Promise rejection tracking
• Detailed environment information collection
• User context support
• Offline support with automatic retry
• Framework-specific integrations
• Breadcrumb tracking for debugging

Installation

NPM/Yarn

# Using npm
npm install @bugmail-js/sdk

# Using yarn
yarn add @bugmail-js/sdk

CDN

<!-- Option A: jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@bugmail-js/[email protected]/dist/bugmail.umd.js"></script>

<!-- Option B: unpkg -->
<script src="https://unpkg.com/@bugmail-js/[email protected]/dist/bugmail.umd.js"></script>

Quick Start

Basic Usage

// Import the SDK
import BugMail from '@bugmail-js/sdk';

// Initialize with your API key
const bugmail = new BugMail({
  apiKey: 'YOUR_PROJECT_API_KEY',
  endpoint: '<your-bugmail-endpoint>',
  environment: 'production' // or 'development', 'staging' for your app environment
});

// Errors will now be automatically captured

CDN Usage

<!-- Define config BEFORE including the SDK to enable auto-initialize -->
<script>
  window.BUGMAIL_CONFIG = {
    apiKey: 'YOUR_PROJECT_API_KEY',
    endpoint: '<your-bugmail-endpoint>',
    environment: 'production',
    enableAIAnalysis: true
  };
  // The SDK auto-initializes only if BUGMAIL_CONFIG exists before the script loads
</script>
<script src="https://cdn.jsdelivr.net/npm/@bugmail-js/[email protected]/dist/bugmail.umd.js"></script>

<!-- Alternatively, initialize manually AFTER the script: -->
<script>
  window.bugmail = new BugMail.BugMailClient({
    apiKey: 'YOUR_PROJECT_API_KEY',
    endpoint: '<your-bugmail-endpoint>',
    environment: 'production'
  });
</script>

Manual Error Capturing

try {
  // Your code that might throw an error
  doSomethingRisky();
} catch (error) {
  // Manually capture the error
  bugmail.captureError(error, {
    // Additional context
    component: 'PaymentForm',
    action: 'processPayment'
  });
}

Setting User Context

// Set user information for better error context
bugmail.setUser({
  id: '123',
  email: '[email protected]',
  name: 'John Doe',
  role: 'admin'
});

Adding Custom Context

// Add any custom data that might help with debugging
bugmail.setContext({
  theme: 'dark',
  plan: 'premium',
  featureFlags: {
    newDashboard: true,
    betaFeatures: false
  }
});

Breadcrumbs

Breadcrumbs help trace user actions leading up to an error:

// Add breadcrumb when user performs important action
bugmail.addBreadcrumb({
  type: 'user',
  message: 'User clicked checkout button',
  level: 'info',
  data: { cartTotal: '$45.67', itemCount: 3 }
});

Framework Integrations

React

import { BugMailProvider, useBugMail, ErrorBoundary } from '@bugmail-js/react';

function App() {
  return (
    <BugMailProvider apiKey="YOUR_API_KEY">
      <ErrorBoundary fallback={<ErrorPage />}>
        <YourApp />
      </ErrorBoundary>
    </BugMailProvider>
  );
}

// In a component
function Component() {
  const bugmail = useBugMail();
  
  const handleClick = () => {
    bugmail.addBreadcrumb({
      type: 'user',
      message: 'Button clicked'
    });
  };
  
  return <button onClick={handleClick}>Click me</button>;
}

Vue.js

import { createApp } from 'vue';
import { bugmailPlugin } from '@bugmail-js/vue';
import App from './App.vue';

const app = createApp(App);
app.use(bugmailPlugin, {
  apiKey: 'YOUR_API_KEY'
});
app.mount('#app');

Configuration Options

const bugmail = new BugMail({
  // Required
  apiKey: 'YOUR_PROJECT_API_KEY',
  endpoint: '<your-bugmail-endpoint>',
  
  // Optional
  environment: 'production', // 'development', 'staging', 'production'
  release: '1.2.3', // Application version
  captureUnhandledErrors: true, // Capture window.onerror
  captureUnhandledRejections: true, // Capture unhandled promises
  captureConsoleErrors: true, // Capture console.error calls
  maxBreadcrumbs: 100, // Maximum breadcrumbs to store
  sampleRate: 1.0, // 1.0 = 100% of errors, 0.5 = 50% of errors
  enableAIAnalysis: true // Enable AI-powered error analysis
});

Backend setup & Auth

The Browser SDK sends error reports to the BugMail backend using your API key for authentication.

Authentication:

• Auth header: x-bugmail-api-key: <YOUR_PROJECT_API_KEY>

Server-side behavior:

• Validates API key and maps it to your project
• Groups errors and stores breadcrumbs
• Enforces plan limits and rate limits (100/minute)
• Optionally runs AI analysis for error groups
• Returns 201 with { status: "success", error_id: "..." } on success

Common responses:

• 400 missing API key or malformed payload
• 401/403 invalid or inactive API key
• 402/403 plan not active or trial expired
• 429 quota exceeded
• 500 internal error

Error Filtering

The BugMail SDK automatically filters out its own internal errors to prevent infinite loops and reduce noise in your error dashboard. This means:

• SDK network errors are logged but not reported
• API validation failures (invalid API key, etc.) don't create loops
• Console messages from the SDK are not captured

What Gets Filtered?

The SDK filters errors that:

• Originate from SDK code (stack trace contains @bugmail-js, bugmail-sdk, etc.)
• Are SDK console messages (start with [BugMail, BugMail Network, etc.)
• Occur during SDK internal operations

Debug Mode

Enable debug mode to see what errors are being filtered and why:

const bugmail = new BugMail({
  apiKey: 'YOUR_API_KEY',
  debug: true  // See filtering decisions in console
});

With debug mode enabled, you'll see messages like:

[BugMail Filter] Filtered: SDK pattern in message
[BugMail Filter] Filtered: SDK pattern in stack trace

Common Scenarios

Invalid API Key:

[BugMail Network] Failed to send error: { status: 401, body: { detail: "Invalid API key" } }

This error is logged once and NOT captured (prevents infinite loop).

Network Error:

[BugMail Network] Failed to send error: { status: 'network_error', message: 'Failed to fetch' }

This error is logged and NOT captured (temporary network issues shouldn't flood your dashboard).

Your Application Error:

TypeError: Cannot read property 'foo' of undefined
    at MyComponent.render (app.js:123)

This error IS captured and sent to your dashboard (it's from your code, not the SDK).

For detailed information about error filtering, see Error Filtering Documentation.

Troubleshooting

SDK not capturing errors

• Ensure your API key is correct
• Check that your application has connectivity to the BugMail API
• Verify that you're not using a Content Security Policy that blocks the API
• Enable debug mode to see detailed logging

SDK errors not appearing in dashboard

This is expected! The SDK filters out its own internal errors to prevent infinite loops. If you see errors in the console with [BugMail] or [BugMail Network] prefixes, these are SDK errors that are intentionally not sent to your dashboard.

To debug SDK issues:

1. Enable debug mode: debug: true in config
2. Check browser console for [BugMail] prefixed messages
3. Check Network tab for failed requests
4. Verify your API key is correct and active

Too many errors reported

• Adjust the sampleRate setting to capture fewer errors
• Add custom logic to filter out repetitive errors using the beforeSend hook

Browser Support

The BugMail SDK supports all modern browsers:

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 16+

For IE11 support, you'll need to include appropriate polyfills.

Documentation

Guides

• Error Filtering Guide - Detailed explanation of how the SDK filters its own errors
• Error Filtering Quick Reference - Quick reference for error filtering
• FAQ - Frequently asked questions

Examples

• See bugmail-sdk/examples/browser-demo for a runnable demo
• See bugmail-sdk/examples/express-server for server-side integration

License

MIT