@bugmail-js/node — Node.js SDK & middleware

This package provides middleware and helpers to integrate BugMail with Node.js servers (Express, Fastify, Koa, Next.js API routes). It wraps the core client and provides request-scoped breadcrumbs and error handlers.

Installation

npm install @bugmail-js/node

Express quickstart.

import express from 'express';
import { middleware } from '@bugmail-js/node';

const app = express();
app.use(express.json());

const config = {
  apiKey: 'YOUR_PROJECT_KEY', // sent as x-bugmail-api-key
  projectId: 'YOUR_PROJECT_ID',
  environment: 'production',
  // Point to your BugMail production API
  baseUrl: process.env.BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>',
};

// Returns { requestHandler, errorHandler }
const { requestHandler, errorHandler } = middleware(config);

// Must be mounted early to initialize request context
app.use(requestHandler);

app.get('/error', (_req, _res) => {
  throw new Error('Test error');
});

// Your routes here

// Final error handler should call the SDK error handler
app.use((err, req, res, next) => {
  // Optional: inspect req.__bugmail.breadcrumbs
  errorHandler(err, req, res, next);
});

app.listen(3000);

API reference

• middleware(config) — returns an object with:

  • requestHandler — Express/Connect middleware to attach a __bugmail context to req and record breadcrumbs for requests
  • errorHandler — Express error-handling middleware that normalizes the error, attaches breadcrumbs, and sends the report to BugMail

• createExpressMiddleware(config) — alternative named export (same as above)

Configuration options:

• apiKey (required) — Your project API key
• projectId (required) — Your project ID
• environment (optional) — Environment name (e.g., 'development', 'production')
• baseUrl (required) — BugMail service endpoint (e.g., <your-bugmail-endpoint>)

Next.js

• This package exports helpers for Next.js API route wrapping (see middleware/next exports).

Examples

• Full example servers are available in bugmail-sdk/examples/:
  • express-server — Express + middleware
  • koa-server — Koa + middleware
  • browser-demo — static browser demo for client SDK
  • fastify-server — planned (folder scaffolded)

The examples demonstrate:

• mounting requestHandler
• adding custom breadcrumbs in routes
• forwarding errors to errorHandler

Best practices

• Mount requestHandler before any route so breadcrumbs capture route hits and middleware actions.
• Call the SDK errorHandler from your final error middleware so every uncaught error is reported with breadcrumbs.
• Use req.__bugmail to access or augment breadcrumbs/context within your routes.
• Use environment variables to manage configuration:

  const config = {
    apiKey: process.env.BUGMAIL_API_KEY,
    projectId: process.env.BUGMAIL_PROJECT_ID,
    environment: process.env.NODE_ENV || 'production',
    baseUrl: process.env.BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>', // BugMail service endpoint
  };

Backend setup & Auth

• Ingestion endpoint used by this middleware: POST <your-bugmail-endpoint>/api/sdk/v1/errors
• Auth header: x-bugmail-api-key: <YOUR_PROJECT_KEY> (case-insensitive)
• Payload shape sent by the middleware:

{
  "error": { "name": "Error", "message": "...", "stack": "..." },
  "context": {
    "request": { "url": "/error", "method": "GET", ... },
    "breadcrumbs": [...],
    "user": { /* optional */ }
  },
  "project_id": "<PROJECT_ID>",
  "environment": "development",
  "user_agent": "...",
  "url": "/error",
  "timestamp": "2025-09-06T15:40:00.000Z"
}

Server responses to expect:

• 201 { status: "success", error_id: "..." } on success
• 400 missing API key / malformed payload
• 401/403 invalid or inactive API key
• 402/403 plan not active or trial expired
• 429 quota exceeded (rate limit 100/min)
• 500 internal error

Troubleshooting

• If the __bugmail context is missing, ensure requestHandler is mounted before other middleware.
• If reports don't reach BugMail, check baseUrl and network connectivity from your server to the BugMail API.

License: MIT

BugMail Node.js SDK

This package contains the Node.js backend SDK implementation.