tracebeam-sdk 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# tracebeam-sdk
+
+A lightweight, non-blocking Node.js SDK for sending errors and events to the TraceBeam API Observability Platform.
+
+## Features
+
+- 🚀 **Non-blocking** - Events queued and sent in background
+- ⚡ **Batching** - Events batched for efficient transmission
+- 🔄 **Retry** - Automatic retry with exponential backoff
+- 🔒 **Secure** - API keys via environment variables
+- 📦 **Lightweight** - Zero runtime dependencies (uses native fetch)
+- 🎯 **TypeScript** - Full type support
+
+## Requirements
+
+- Node.js 18+
+
+## Installation
+
+```bash
+npm install tracebeam-sdk
+```
+
+## Quick Start
+
+```typescript
+import { TraceBeamSDK } from 'tracebeam-sdk';
+
+// Initialize from environment variables
+const sdk = TraceBeamSDK.fromEnv();
+
+// Capture an exception
+try {
+  await doSomething();
+} catch (error) {
+  sdk.captureException(error);
+}
+
+// Capture a message
+sdk.captureMessage('User signed up', { level: 'info' });
+
+// Graceful shutdown
+await sdk.close();
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TRACEBEAM_API_KEY` | Yes | - | Your API key |
+| `TRACEBEAM_PROJECT_ID` | Yes | - | Your project ID |
+| `TRACEBEAM_ENVIRONMENT` | No | development | Environment name |
+| `TRACEBEAM_ENDPOINT` | No | https://ingest.tracebeam.io | API endpoint |
+| `TRACEBEAM_BATCH_SIZE` | No | 100 | Events per batch |
+| `TRACEBEAM_FLUSH_INTERVAL` | No | 5000 | Flush interval (ms) |
+| `TRACEBEAM_DEBUG` | No | false | Enable debug logging |
+
+## Manual Configuration
+
+```typescript
+const sdk = new TraceBeamSDK({
+  apiKey: 'sk_xxx',
+  projectId: 'proj_xxx',
+  environment: 'production',
+  batchSize: 50,
+  flushInterval: 3000,
+});
+```
+
+## Context
+
+```typescript
+// Set user context
+sdk.setUser('user_123');
+
+// Set tags (included in all events)
+sdk.setTag('region', 'us-east-1');
+sdk.setTags({ service: 'api', version: '1.0.0' });
+
+// Set extra context
+sdk.setExtra('account_type', 'premium');
+```
+
+## Framework Integrations
+
+### Express
+
+```typescript
+import express from 'express';
+import { TraceBeamSDK } from 'tracebeam-sdk';
+import { expressErrorHandler } from 'tracebeam-sdk/integrations/express';
+
+const app = express();
+const sdk = TraceBeamSDK.fromEnv();
+
+// Your routes...
+
+// Add error handler AFTER all routes
+app.use(expressErrorHandler(sdk));
+```
+
+### Fastify
+
+```typescript
+import Fastify from 'fastify';
+import { TraceBeamSDK } from 'tracebeam-sdk';
+import { tracebeamPlugin } from 'tracebeam-sdk/integrations/fastify';
+
+const fastify = Fastify();
+const sdk = TraceBeamSDK.fromEnv();
+
+fastify.register(tracebeamPlugin, { sdk });
+```
+
+## Capture Options
+
+```typescript
+sdk.captureException(error, {
+  level: 'fatal',
+  tags: { feature: 'auth' },
+  extra: { userId: '123', endpoint: '/login' },
+});
+
+sdk.captureMessage('Important event', {
+  level: 'warning',
+  tags: { category: 'billing' },
+});
+```
+
+## Graceful Shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+  await sdk.close();
+  process.exit(0);
+});
+```
+
+## License
+
+MIT

package/dist/client-CaHega3m.d.mts

@@ -0,0 +1,207 @@
+/**
+ * SDK configuration options
+ */
+interface TraceBeamConfig {
+    /** API key for authentication (required) */
+    apiKey: string;
+    /** Project ID to send events for (required) */
+    projectId: string;
+    /** Environment name (default: 'development') */
+    environment?: string;
+    /** Ingest API endpoint (default: 'https://ingest.tracebeam.io') */
+    endpoint?: string;
+    /** Max events per batch (default: 100) */
+    batchSize?: number;
+    /** Flush interval in milliseconds (default: 5000) */
+    flushInterval?: number;
+    /** HTTP request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Max events to hold in queue (default: 10000) */
+    maxQueueSize?: number;
+    /** Sample rate 0.0-1.0 (default: 1.0) */
+    sampleRate?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Event severity levels
+ */
+type EventLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+/**
+ * Tags for event categorization
+ */
+type Tags = Record<string, string>;
+/**
+ * Extra context data for events
+ */
+type Extra = Record<string, unknown>;
+/**
+ * Event payload sent to the Ingest API
+ */
+interface Event {
+    /** Project ID */
+    project_id: string;
+    /** Error message or event description */
+    error: string;
+    /** Severity level */
+    level: EventLevel;
+    /** Environment (prod, staging, dev) */
+    environment: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Key-value tags for categorization */
+    tags: Tags;
+    /** Additional context data */
+    extra: Extra;
+}
+/**
+ * Options for capture methods
+ */
+interface CaptureOptions {
+    /** Severity level */
+    level?: EventLevel;
+    /** Additional tags */
+    tags?: Tags;
+    /** Additional context */
+    extra?: Extra;
+    /** Custom timestamp (ISO 8601) */
+    timestamp?: string;
+}
+/**
+ * Batch payload sent to Ingest API
+ */
+interface EventBatch {
+    events: Event[];
+}
+/**
+ * Success response from Ingest API
+ */
+interface TransportSuccessResponse {
+    success: true;
+    events_accepted: number;
+    message: string;
+}
+/**
+ * Error response from Ingest API
+ */
+interface TransportErrorResponse {
+    success: false;
+    error: string;
+    message: string;
+    code: number;
+    retry_after?: number;
+}
+/**
+ * Transport response (success or error)
+ */
+type TransportResponse = TransportSuccessResponse | TransportErrorResponse;
+
+/**
+ * TraceBeamSDK client for capturing and sending events
+ *
+ * @example
+ * ```typescript
+ * // Initialize from environment variables
+ * const sdk = TraceBeamSDK.fromEnv();
+ *
+ * // Capture an exception
+ * try {
+ *   doSomething();
+ * } catch (error) {
+ *   sdk.captureException(error);
+ * }
+ *
+ * // Capture a message
+ * sdk.captureMessage('User signup completed', {
+ *   level: 'info',
+ *   tags: { feature: 'auth' }
+ * });
+ *
+ * // Graceful shutdown
+ * await sdk.close();
+ * ```
+ */
+declare class TraceBeamSDK {
+    private readonly config;
+    private readonly transport;
+    private readonly queue;
+    private globalTags;
+    private globalExtra;
+    private userId;
+    private isInitialized;
+    /**
+     * Create SDK instance from configuration
+     */
+    constructor(config: TraceBeamConfig);
+    /**
+     * Create SDK instance from environment variables
+     *
+     * Required env vars:
+     * - TRACEBEAM_API_KEY
+     * - TRACEBEAM_PROJECT_ID
+     *
+     * Optional env vars:
+     * - TRACEBEAM_ENVIRONMENT (default: 'development')
+     * - TRACEBEAM_ENDPOINT (default: 'https://ingest.tracebeam.io')
+     * - TRACEBEAM_BATCH_SIZE (default: 100)
+     * - TRACEBEAM_FLUSH_INTERVAL (default: 5000)
+     * - TRACEBEAM_HTTP_TIMEOUT (default: 10000)
+     * - TRACEBEAM_MAX_QUEUE_SIZE (default: 10000)
+     * - TRACEBEAM_SAMPLE_RATE (default: 1.0)
+     * - TRACEBEAM_DEBUG (default: false)
+     */
+    static fromEnv(): TraceBeamSDK;
+    /**
+     * Capture an exception/error
+     * Returns immediately (non-blocking)
+     */
+    captureException(error: Error | string, options?: CaptureOptions): void;
+    /**
+     * Capture a message/event
+     * Returns immediately (non-blocking)
+     */
+    captureMessage(message: string, options?: CaptureOptions): void;
+    /**
+     * Set the current user ID
+     * Will be included in all subsequent events
+     */
+    setUser(userId: string | null): void;
+    /**
+     * Set a global tag
+     * Will be included in all subsequent events
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Set multiple global tags
+     * Will be included in all subsequent events
+     */
+    setTags(tags: Tags): void;
+    /**
+     * Set global extra context
+     * Will be included in all subsequent events
+     */
+    setExtra(key: string, value: unknown): void;
+    /**
+     * Set multiple global extra context values
+     */
+    setExtras(extras: Extra): void;
+    /**
+     * Manually flush queued events
+     * Call this to ensure events are sent before process exit
+     */
+    flush(): Promise<void>;
+    /**
+     * Graceful shutdown
+     * Flushes remaining events and stops background workers
+     */
+    close(): Promise<void>;
+    /**
+     * Check if SDK is active and can capture events
+     */
+    isActive(): boolean;
+    private canCapture;
+    private createEventWithContext;
+    private handleFlush;
+}
+
+export { type CaptureOptions as C, type Event as E, type TraceBeamConfig as T, TraceBeamSDK as a, type EventLevel as b, type Tags as c, type Extra as d, type EventBatch as e, type TransportResponse as f, type TransportSuccessResponse as g, type TransportErrorResponse as h };

package/dist/client-CaHega3m.d.ts

@@ -0,0 +1,207 @@
+/**
+ * SDK configuration options
+ */
+interface TraceBeamConfig {
+    /** API key for authentication (required) */
+    apiKey: string;
+    /** Project ID to send events for (required) */
+    projectId: string;
+    /** Environment name (default: 'development') */
+    environment?: string;
+    /** Ingest API endpoint (default: 'https://ingest.tracebeam.io') */
+    endpoint?: string;
+    /** Max events per batch (default: 100) */
+    batchSize?: number;
+    /** Flush interval in milliseconds (default: 5000) */
+    flushInterval?: number;
+    /** HTTP request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Max events to hold in queue (default: 10000) */
+    maxQueueSize?: number;
+    /** Sample rate 0.0-1.0 (default: 1.0) */
+    sampleRate?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Event severity levels
+ */
+type EventLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+/**
+ * Tags for event categorization
+ */
+type Tags = Record<string, string>;
+/**
+ * Extra context data for events
+ */
+type Extra = Record<string, unknown>;
+/**
+ * Event payload sent to the Ingest API
+ */
+interface Event {
+    /** Project ID */
+    project_id: string;
+    /** Error message or event description */
+    error: string;
+    /** Severity level */
+    level: EventLevel;
+    /** Environment (prod, staging, dev) */
+    environment: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Key-value tags for categorization */
+    tags: Tags;
+    /** Additional context data */
+    extra: Extra;
+}
+/**
+ * Options for capture methods
+ */
+interface CaptureOptions {
+    /** Severity level */
+    level?: EventLevel;
+    /** Additional tags */
+    tags?: Tags;
+    /** Additional context */
+    extra?: Extra;
+    /** Custom timestamp (ISO 8601) */
+    timestamp?: string;
+}
+/**
+ * Batch payload sent to Ingest API
+ */
+interface EventBatch {
+    events: Event[];
+}
+/**
+ * Success response from Ingest API
+ */
+interface TransportSuccessResponse {
+    success: true;
+    events_accepted: number;
+    message: string;
+}
+/**
+ * Error response from Ingest API
+ */
+interface TransportErrorResponse {
+    success: false;
+    error: string;
+    message: string;
+    code: number;
+    retry_after?: number;
+}
+/**
+ * Transport response (success or error)
+ */
+type TransportResponse = TransportSuccessResponse | TransportErrorResponse;
+
+/**
+ * TraceBeamSDK client for capturing and sending events
+ *
+ * @example
+ * ```typescript
+ * // Initialize from environment variables
+ * const sdk = TraceBeamSDK.fromEnv();
+ *
+ * // Capture an exception
+ * try {
+ *   doSomething();
+ * } catch (error) {
+ *   sdk.captureException(error);
+ * }
+ *
+ * // Capture a message
+ * sdk.captureMessage('User signup completed', {
+ *   level: 'info',
+ *   tags: { feature: 'auth' }
+ * });
+ *
+ * // Graceful shutdown
+ * await sdk.close();
+ * ```
+ */
+declare class TraceBeamSDK {
+    private readonly config;
+    private readonly transport;
+    private readonly queue;
+    private globalTags;
+    private globalExtra;
+    private userId;
+    private isInitialized;
+    /**
+     * Create SDK instance from configuration
+     */
+    constructor(config: TraceBeamConfig);
+    /**
+     * Create SDK instance from environment variables
+     *
+     * Required env vars:
+     * - TRACEBEAM_API_KEY
+     * - TRACEBEAM_PROJECT_ID
+     *
+     * Optional env vars:
+     * - TRACEBEAM_ENVIRONMENT (default: 'development')
+     * - TRACEBEAM_ENDPOINT (default: 'https://ingest.tracebeam.io')
+     * - TRACEBEAM_BATCH_SIZE (default: 100)
+     * - TRACEBEAM_FLUSH_INTERVAL (default: 5000)
+     * - TRACEBEAM_HTTP_TIMEOUT (default: 10000)
+     * - TRACEBEAM_MAX_QUEUE_SIZE (default: 10000)
+     * - TRACEBEAM_SAMPLE_RATE (default: 1.0)
+     * - TRACEBEAM_DEBUG (default: false)
+     */
+    static fromEnv(): TraceBeamSDK;
+    /**
+     * Capture an exception/error
+     * Returns immediately (non-blocking)
+     */
+    captureException(error: Error | string, options?: CaptureOptions): void;
+    /**
+     * Capture a message/event
+     * Returns immediately (non-blocking)
+     */
+    captureMessage(message: string, options?: CaptureOptions): void;
+    /**
+     * Set the current user ID
+     * Will be included in all subsequent events
+     */
+    setUser(userId: string | null): void;
+    /**
+     * Set a global tag
+     * Will be included in all subsequent events
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Set multiple global tags
+     * Will be included in all subsequent events
+     */
+    setTags(tags: Tags): void;
+    /**
+     * Set global extra context
+     * Will be included in all subsequent events
+     */
+    setExtra(key: string, value: unknown): void;
+    /**
+     * Set multiple global extra context values
+     */
+    setExtras(extras: Extra): void;
+    /**
+     * Manually flush queued events
+     * Call this to ensure events are sent before process exit
+     */
+    flush(): Promise<void>;
+    /**
+     * Graceful shutdown
+     * Flushes remaining events and stops background workers
+     */
+    close(): Promise<void>;
+    /**
+     * Check if SDK is active and can capture events
+     */
+    isActive(): boolean;
+    private canCapture;
+    private createEventWithContext;
+    private handleFlush;
+}
+
+export { type CaptureOptions as C, type Event as E, type TraceBeamConfig as T, TraceBeamSDK as a, type EventLevel as b, type Tags as c, type Extra as d, type EventBatch as e, type TransportResponse as f, type TransportSuccessResponse as g, type TransportErrorResponse as h };

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+import { T as TraceBeamConfig } from './client-CaHega3m.mjs';
+export { C as CaptureOptions, E as Event, e as EventBatch, b as EventLevel, d as Extra, c as Tags, a as TraceBeamSDK, h as TransportErrorResponse, f as TransportResponse, g as TransportSuccessResponse } from './client-CaHega3m.mjs';
+
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: {
+    readonly environment: "development";
+    readonly endpoint: "https://ingest.tracebeam.io";
+    readonly batchSize: 100;
+    readonly flushInterval: 5000;
+    readonly timeout: 10000;
+    readonly maxQueueSize: 10000;
+    readonly sampleRate: 1;
+    readonly debug: false;
+};
+/**
+ * Configuration error thrown when required values are missing
+ */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load configuration from environment variables
+ */
+declare function loadConfigFromEnv(): TraceBeamConfig;
+
+export { ConfigError, DEFAULT_CONFIG, TraceBeamConfig, loadConfigFromEnv };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { T as TraceBeamConfig } from './client-CaHega3m.js';
+export { C as CaptureOptions, E as Event, e as EventBatch, b as EventLevel, d as Extra, c as Tags, a as TraceBeamSDK, h as TransportErrorResponse, f as TransportResponse, g as TransportSuccessResponse } from './client-CaHega3m.js';
+
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: {
+    readonly environment: "development";
+    readonly endpoint: "https://ingest.tracebeam.io";
+    readonly batchSize: 100;
+    readonly flushInterval: 5000;
+    readonly timeout: 10000;
+    readonly maxQueueSize: 10000;
+    readonly sampleRate: 1;
+    readonly debug: false;
+};
+/**
+ * Configuration error thrown when required values are missing
+ */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load configuration from environment variables
+ */
+declare function loadConfigFromEnv(): TraceBeamConfig;
+
+export { ConfigError, DEFAULT_CONFIG, TraceBeamConfig, loadConfigFromEnv };