@helpgrid/core

Shared foundation for HelpGrid Signals error tracking SDK. Provides core error capture, transport, and scope management functionality.

Installation

npm install @helpgrid/core
# or
pnpm add @helpgrid/core

Quick Start

import { SignalsClient, captureException } from '@helpgrid/core';

// Initialize SDK
SignalsClient.init({
  apiKey: 'your-api-key',
  environment: 'production'
});

// Capture exceptions
try {
  riskyOperation();
} catch (error) {
  captureException(error);
}

API Reference

SignalsClient.init(options)

Initialize the SDK with configuration options.

Options:

• apiKey (required): Your HelpGrid API key
• endpoint: API endpoint (default: https://helpgrid.dev/api/signals/ingest)
• environment: Environment name (default: production)
• release: Release version for tracking
• sampleRate: Sample rate 0-1 (default: 1 = 100%)
• maxBreadcrumbs: Max breadcrumbs to keep (default: 100)
• beforeSend: Callback to modify events before sending
• ignoreErrors: Array of error patterns to ignore

captureException(error, context?)

Capture an exception with optional context.

captureException(new Error('Something failed'), {
  tags: { component: 'payment' },
  extra: { orderId: '123' }
});

captureMessage(message, level?, context?)

Capture a message at specified severity level.

captureMessage('User logged in', 'info', {
  tags: { userId: '456' }
});

withScope(callback)

Execute callback within a new scope.

withScope((scope) => {
  scope.setTag('feature', 'checkout');
  scope.setUser({ id: '789' });

  captureException(error);
});

Scope Methods

const scope = getScope();

scope.setTag(key, value);
scope.setTags({ key1: 'value1', key2: 'value2' });
scope.setExtra(key, value);
scope.setExtras({ key1: {}, key2: {} });
scope.setUser({ id: '123', email: '[email protected]' });
scope.addBreadcrumb({ message: 'User clicked button', category: 'ui' });
scope.clearBreadcrumbs();

Features

• ✅ Error fingerprinting (SHA-256)
• ✅ Stack trace parsing
• ✅ Scope management
• ✅ Breadcrumb tracking
• ✅ Event filtering and sampling
• ✅ Workers-compatible (no AsyncLocalStorage)
• ✅ Minimal overhead (no dependencies)

Workers Compatibility

This SDK works in Cloudflare Workers and other edge runtimes:

// Use manual scope management for Workers
SignalsClient.init({
  apiKey: env.HELPGRID_API_KEY,
  environment: 'production'
});

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    try {
      // Your handler
    } catch (error) {
      withScope((scope) => {
        scope.setTag('method', request.method);
        captureException(error);
      });
    }
  }
};

Development

pnpm install
pnpm build
pnpm test

License

MIT