@bugmail-js/core — Core utilities for BugMail SDKs

This package contains framework-agnostic building blocks used by the BugMail JavaScript SDKs (browser, Node, and server integrations).

Use this package if you are building a custom integration or need low-level control. It exports small, well-scoped classes for capturing errors, tracking breadcrumbs, and sending reports.

Highlights

• BugMailCoreClient — lightweight client that prepares and sends error payloads to the BugMail backend.
• BreadcrumbTracker — record user events leading up to an error.
• CoreNetworkManager, CoreErrorProcessor — helpers for networking and normalization.

Installation

Typically you do not need to install this directly; other SDK packages depend on it. If you need it directly:

npm install @bugmail-js/core

Quick example (capture an exception)

import { BugMailCoreClient } from '@bugmail-js/core';

const client = new BugMailCoreClient({
  baseUrl: process.env.BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>',
  apiPath: '/api/sdk/v1/errors',
  onError: (info) => console.warn('Reporting failed', info),
});

await client.captureException(new Error('Test error'), {
  headers: { 'x-bugmail-api-key': 'YOUR_PROJECT_API_KEY' },
  payload: {
    error: { name: 'Error', message: 'Test error', stack: '...' },
    context: { url: '/test', environment: 'development' }
  },
});

API reference (important parts)

• new BugMailCoreClient(config)

  • config.baseUrl — backend base URL (default: env BUGMAIL_API_BASE_URL or <your-bugmail-endpoint>)
  • config.apiPath — ingestion path (default: /api/sdk/v1/errors)
  • config.onError — optional callback invoked when report fails

• captureException(error, context)

  • error — Error object or any serializable value
  • context — optional object: { headers, payload, user, breadcrumbs }
    • Include headers: { 'x-bugmail-api-key': '<YOUR_PROJECT_API_KEY>' }

• BreadcrumbTracker

  • new BreadcrumbTracker({ maxBreadcrumbs })
  • record(breadcrumb) — add a breadcrumb object
  • recordCustom(message, category, data, level)
  • recordRequest(requestData) — convenience for HTTP breadcrumbs
  • getBreadcrumbs(), clear()

Advanced

• CoreNetworkManager and CoreErrorProcessor are exported for advanced integration points (custom retries, queueing, or server-side normalization).

Integration notes

• The core package is intentionally minimal and has no browser-only dependencies. Browser and Node SDKs re-export and extend it with environment-specific behavior (automatic capture, global handlers, middleware, etc.).

Backend integration & headers

• Ingestion endpoint: POST {baseUrl}/api/sdk/v1/errors
• Auth header: x-bugmail-api-key: <YOUR_PROJECT_API_KEY>
• Note: HTTP header names are case-insensitive; use the canonical lowercase form above for consistency.
• Typical payload shape:

{
  "error": { "name": "TypeError", "message": "...", "stack": "..." },
  "context": { "breadcrumbs": [...], "request": { ... } },
  "timestamp": "2025-09-06T15:40:00.000Z",
  "environment": "production"
}

The backend validates the API key, groups the error, stores breadcrumbs, enforces rate/plan limits, may run AI analysis, and returns 201 with { status: "success", error_id: "..." }.

Contributing

Please follow the repository contributing guidelines. Tests and simple usage examples are appreciated.

Shared core logic for BugMail SDKs

This package will contain shared logic for Node.js and Django SDKs.