bugcatch-sdk 0.1.0

package/README.md

@@ -0,0 +1,233 @@
+# bugcatch-sdk
+
+Official JavaScript/TypeScript SDK for [BugCatch](https://github.com/your-org/bugcatch) — lightweight error tracking for web and Node.js applications.
+
+## Features
+
+- Automatic capture of uncaught errors and unhandled promise rejections
+- Manual `captureException` and `captureMessage` APIs
+- Breadcrumb trail: clicks, navigation, console calls
+- User context and custom tags
+- `beforeSend` hook to filter or modify events before sending
+- Works in the browser (modern bundlers + CDN) and Node.js
+- Zero runtime dependencies — ~15 KB minified
+
+---
+
+## Installation
+
+```bash
+npm install bugcatch-sdk
+```
+
+---
+
+## Quick Start
+
+```typescript
+import BugCatch from 'bugcatch-sdk';
+
+BugCatch.init({
+  dsn: 'http://localhost:3000/ingest/<projectId>?key=<sdkKey>',
+  release: '1.0.0',
+  environment: 'production',
+});
+```
+
+The DSN is available on your project page in the BugCatch dashboard.
+
+From this point on, all uncaught errors and unhandled promise rejections are captured automatically.
+
+---
+
+## Manual Captures
+
+```typescript
+// Capture an Error object
+try {
+  await processOrder(order);
+} catch (err) {
+  BugCatch.captureException(err, { orderId: order.id });
+}
+
+// Capture a plain message
+BugCatch.captureMessage('Quota limit reached', 'warning', { used: 95 });
+```
+
+---
+
+## User Context
+
+```typescript
+// After login
+BugCatch.setUser({ id: '42', email: 'jane@example.com', username: 'jane' });
+
+// After logout
+BugCatch.clearUser();
+```
+
+---
+
+## Tags
+
+```typescript
+BugCatch.setTag('plan', 'pro');
+BugCatch.setTag('region', 'eu-west-1');
+```
+
+---
+
+## Options
+
+```typescript
+BugCatch.init({
+  // Required
+  dsn: string;
+
+  // Optional
+  release?: string;               // App version e.g. "1.2.3"
+  environment?: string;           // "production" | "staging" | ...
+  debug?: boolean;                // Print SDK logs to console (default: false)
+  maxBreadcrumbs?: number;        // Max breadcrumbs kept in memory (default: 100)
+  autoCaptureErrors?: boolean;    // Auto-attach global error handlers (default: true)
+  autoCaptureBreadcrumbs?: boolean; // Auto-capture clicks, nav, console (default: true)
+
+  // Drop errors whose message matches any of these
+  ignoreErrors?: Array<string | RegExp>;
+
+  // Drop errors originating from matching script URLs
+  ignoreUrls?: Array<string | RegExp>;
+
+  // Modify or drop an event before it is sent. Return false to discard.
+  beforeSend?: (event: EventPayload) => EventPayload | false;
+});
+```
+
+---
+
+## Framework Examples
+
+### React
+
+```tsx
+// src/main.tsx
+import BugCatch from 'bugcatch-sdk';
+
+BugCatch.init({
+  dsn: import.meta.env.VITE_BUGCATCH_DSN,
+  release: import.meta.env.VITE_APP_VERSION,
+  environment: import.meta.env.MODE,
+});
+```
+
+**Error boundary:**
+
+```tsx
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error: Error) {
+    BugCatch.captureException(error);
+  }
+  render() {
+    return this.props.children;
+  }
+}
+```
+
+### Vue
+
+```ts
+// src/main.ts
+import BugCatch from 'bugcatch-sdk';
+
+BugCatch.init({ dsn: import.meta.env.VITE_BUGCATCH_DSN });
+
+app.config.errorHandler = (err) => {
+  BugCatch.captureException(err);
+};
+```
+
+### Node.js / Express
+
+```typescript
+import BugCatch from 'bugcatch-sdk';
+
+BugCatch.init({
+  dsn: process.env.BUGCATCH_DSN!,
+  release: process.env.npm_package_version,
+  environment: process.env.NODE_ENV,
+  autoCaptureBreadcrumbs: false, // no DOM in Node.js
+});
+
+// Error middleware
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  BugCatch.captureException(err, { path: req.path, method: req.method });
+  next(err);
+});
+```
+
+### CommonJS
+
+```javascript
+const { BugCatch } = require('bugcatch-sdk');
+
+BugCatch.init({ dsn: process.env.BUGCATCH_DSN });
+```
+
+---
+
+## Breadcrumbs
+
+Breadcrumbs are short records of what happened before an error. The SDK captures them automatically when `autoCaptureBreadcrumbs: true` (default):
+
+| Source | Category | What is recorded |
+|--------|----------|-----------------|
+| DOM clicks | `ui.click` | Element tag, text, id/class |
+| History navigation | `navigation` | URL navigated to |
+| `console.warn` / `console.error` | `console` | Message text |
+
+Add breadcrumbs manually:
+
+```typescript
+BugCatch.addBreadcrumb({
+  timestamp: new Date().toISOString(),
+  type: 'user',
+  category: 'auth',
+  message: 'User logged in',
+  data: { method: 'google-oauth' },
+});
+```
+
+---
+
+## beforeSend
+
+Use `beforeSend` to scrub sensitive data or drop specific events:
+
+```typescript
+BugCatch.init({
+  dsn: '...',
+  beforeSend(event) {
+    // Drop network errors
+    if (event.exception?.values?.[0]?.type === 'NetworkError') return false;
+
+    // Scrub email from user context
+    if (event.user) delete event.user.email;
+
+    return event;
+  },
+});
+```
+
+---
+
+## SPA / Hot-Reload Cleanup
+
+```typescript
+BugCatch.destroy(); // removes all listeners, resets singleton
+```
+
+---
+
+## License
+
+ISC

package/dist/index.d.mts

@@ -0,0 +1,159 @@
+interface BugCatchOptions {
+    /** DSN from the BugCatch dashboard. Format: http://host/ingest/{projectId}?key={sdkKey} */
+    dsn: string;
+    /** Application release version, e.g. "1.2.3". Attached to every event. */
+    release?: string;
+    /** Deployment environment, e.g. "production" | "staging". Attached to every event. */
+    environment?: string;
+    /** Print debug info to the console. Default: false. */
+    debug?: boolean;
+    /** Max breadcrumbs to keep in memory. Default: 100. */
+    maxBreadcrumbs?: number;
+    /**
+     * Automatically attach global error handlers and capture breadcrumbs.
+     * Default: true. Set to false to manage captures manually.
+     */
+    autoCaptureErrors?: boolean;
+    /**
+     * Automatically capture breadcrumbs from clicks, navigation, and console.
+     * Default: true.
+     */
+    autoCaptureBreadcrumbs?: boolean;
+    /**
+     * A list of URL patterns (strings or RegExps). Any error originating from
+     * a script URL that matches will be ignored.
+     */
+    ignoreUrls?: Array<string | RegExp>;
+    /**
+     * A list of error message patterns (strings or RegExps). Matching errors
+     * will be dropped before being sent.
+     */
+    ignoreErrors?: Array<string | RegExp>;
+    /** Called before an event is sent. Return false to drop the event. */
+    beforeSend?: (event: EventPayload) => EventPayload | false;
+}
+interface UserContext {
+    id?: string;
+    email?: string;
+    username?: string;
+}
+interface BreadcrumbEntry {
+    timestamp: string;
+    type?: string;
+    category?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+interface StackFrame {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    function?: string;
+    context_line?: string;
+    in_app?: boolean;
+}
+interface ExceptionValue {
+    type?: string;
+    value?: string;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+}
+interface EventPayload {
+    event_id: string;
+    timestamp: string;
+    level?: string;
+    message?: string;
+    platform: string;
+    release?: string;
+    environment?: string;
+    user?: UserContext;
+    request?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+    };
+    exception?: {
+        values: ExceptionValue[];
+    };
+    breadcrumbs?: BreadcrumbEntry[];
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+interface ParsedDsn {
+    /** Full URL including path and query, e.g. http://host/ingest/projectId?key=xyz */
+    ingestUrl: string;
+    projectId: string;
+    sdkKey: string;
+}
+
+declare class BugCatchClient {
+    private readonly opts;
+    private readonly dsn;
+    private readonly crumbs;
+    private user;
+    private tags;
+    private readonly cleanups;
+    constructor(options: BugCatchOptions);
+    captureException(error: unknown, extra?: Record<string, unknown>): string;
+    captureMessage(message: string, level?: string, extra?: Record<string, unknown>): string;
+    setUser(user: UserContext): void;
+    clearUser(): void;
+    setTag(key: string, value: string): void;
+    addBreadcrumb(crumb: BreadcrumbEntry): void;
+    /** Tear down all global listeners. Call when unmounting in SPAs. */
+    destroy(): void;
+    private buildExceptionPayload;
+    private buildMessagePayload;
+    private buildBase;
+    private installErrorHandlers;
+    private shouldIgnore;
+    private send;
+    private log;
+}
+
+declare const BugCatch: {
+    /**
+     * Initialize the SDK. Call this once, as early as possible in your app.
+     *
+     * @example
+     * BugCatch.init({
+     *   dsn: 'http://localhost:3000/ingest/project-id?key=sdk-key',
+     *   release: '1.0.0',
+     *   environment: 'production',
+     * });
+     */
+    init(options: BugCatchOptions): BugCatchClient;
+    /**
+     * Capture an Error object or any value as an error event.
+     * Returns the generated event_id.
+     */
+    captureException(error: unknown, extra?: Record<string, unknown>): string;
+    /**
+     * Capture a plain text message as an event.
+     * Returns the generated event_id.
+     */
+    captureMessage(message: string, level?: string, extra?: Record<string, unknown>): string;
+    /**
+     * Set the current user context. Attached to all subsequent events.
+     */
+    setUser(user: UserContext): void;
+    /**
+     * Clear the current user context (e.g. on logout).
+     */
+    clearUser(): void;
+    /**
+     * Set a tag that will be attached to all subsequent events.
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Manually add a breadcrumb.
+     */
+    addBreadcrumb(crumb: BreadcrumbEntry): void;
+    /**
+     * Tear down all listeners. Useful in SPA cleanup or hot-reload scenarios.
+     */
+    destroy(): void;
+};
+
+export { type BreadcrumbEntry, BugCatch, BugCatchClient, type BugCatchOptions, type EventPayload, type ParsedDsn, type StackFrame, type UserContext, BugCatch as default };

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+interface BugCatchOptions {
+    /** DSN from the BugCatch dashboard. Format: http://host/ingest/{projectId}?key={sdkKey} */
+    dsn: string;
+    /** Application release version, e.g. "1.2.3". Attached to every event. */
+    release?: string;
+    /** Deployment environment, e.g. "production" | "staging". Attached to every event. */
+    environment?: string;
+    /** Print debug info to the console. Default: false. */
+    debug?: boolean;
+    /** Max breadcrumbs to keep in memory. Default: 100. */
+    maxBreadcrumbs?: number;
+    /**
+     * Automatically attach global error handlers and capture breadcrumbs.
+     * Default: true. Set to false to manage captures manually.
+     */
+    autoCaptureErrors?: boolean;
+    /**
+     * Automatically capture breadcrumbs from clicks, navigation, and console.
+     * Default: true.
+     */
+    autoCaptureBreadcrumbs?: boolean;
+    /**
+     * A list of URL patterns (strings or RegExps). Any error originating from
+     * a script URL that matches will be ignored.
+     */
+    ignoreUrls?: Array<string | RegExp>;
+    /**
+     * A list of error message patterns (strings or RegExps). Matching errors
+     * will be dropped before being sent.
+     */
+    ignoreErrors?: Array<string | RegExp>;
+    /** Called before an event is sent. Return false to drop the event. */
+    beforeSend?: (event: EventPayload) => EventPayload | false;
+}
+interface UserContext {
+    id?: string;
+    email?: string;
+    username?: string;
+}
+interface BreadcrumbEntry {
+    timestamp: string;
+    type?: string;
+    category?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+interface StackFrame {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    function?: string;
+    context_line?: string;
+    in_app?: boolean;
+}
+interface ExceptionValue {
+    type?: string;
+    value?: string;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+}
+interface EventPayload {
+    event_id: string;
+    timestamp: string;
+    level?: string;
+    message?: string;
+    platform: string;
+    release?: string;
+    environment?: string;
+    user?: UserContext;
+    request?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+    };
+    exception?: {
+        values: ExceptionValue[];
+    };
+    breadcrumbs?: BreadcrumbEntry[];
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+interface ParsedDsn {
+    /** Full URL including path and query, e.g. http://host/ingest/projectId?key=xyz */
+    ingestUrl: string;
+    projectId: string;
+    sdkKey: string;
+}
+
+declare class BugCatchClient {
+    private readonly opts;
+    private readonly dsn;
+    private readonly crumbs;
+    private user;
+    private tags;
+    private readonly cleanups;
+    constructor(options: BugCatchOptions);
+    captureException(error: unknown, extra?: Record<string, unknown>): string;
+    captureMessage(message: string, level?: string, extra?: Record<string, unknown>): string;
+    setUser(user: UserContext): void;
+    clearUser(): void;
+    setTag(key: string, value: string): void;
+    addBreadcrumb(crumb: BreadcrumbEntry): void;
+    /** Tear down all global listeners. Call when unmounting in SPAs. */
+    destroy(): void;
+    private buildExceptionPayload;
+    private buildMessagePayload;
+    private buildBase;
+    private installErrorHandlers;
+    private shouldIgnore;
+    private send;
+    private log;
+}
+
+declare const BugCatch: {
+    /**
+     * Initialize the SDK. Call this once, as early as possible in your app.
+     *
+     * @example
+     * BugCatch.init({
+     *   dsn: 'http://localhost:3000/ingest/project-id?key=sdk-key',
+     *   release: '1.0.0',
+     *   environment: 'production',
+     * });
+     */
+    init(options: BugCatchOptions): BugCatchClient;
+    /**
+     * Capture an Error object or any value as an error event.
+     * Returns the generated event_id.
+     */
+    captureException(error: unknown, extra?: Record<string, unknown>): string;
+    /**
+     * Capture a plain text message as an event.
+     * Returns the generated event_id.
+     */
+    captureMessage(message: string, level?: string, extra?: Record<string, unknown>): string;
+    /**
+     * Set the current user context. Attached to all subsequent events.
+     */
+    setUser(user: UserContext): void;
+    /**
+     * Clear the current user context (e.g. on logout).
+     */
+    clearUser(): void;
+    /**
+     * Set a tag that will be attached to all subsequent events.
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Manually add a breadcrumb.
+     */
+    addBreadcrumb(crumb: BreadcrumbEntry): void;
+    /**
+     * Tear down all listeners. Useful in SPA cleanup or hot-reload scenarios.
+     */
+    destroy(): void;
+};
+
+export { type BreadcrumbEntry, BugCatch, BugCatchClient, type BugCatchOptions, type EventPayload, type ParsedDsn, type StackFrame, type UserContext, BugCatch as default };