@vantatrace/sdk 0.1.0

package/dist/context.d.ts

@@ -0,0 +1,17 @@
+export declare function getSystemContext(): {
+    nodeVersion: string;
+    hostname: string;
+    pid: number;
+    platform: NodeJS.Platform;
+    arch: string;
+    memory: {
+        rss: number;
+        heapTotal: number;
+        heapUsed: number;
+        external: number;
+        freeMem: number;
+        totalMem: number;
+    };
+    loadavg: number[];
+    uptime: number;
+};

package/dist/context.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSystemContext = getSystemContext;
+const os = __importStar(require("os"));
+function getSystemContext() {
+    const memoryUsage = process.memoryUsage();
+    return {
+        nodeVersion: process.version,
+        hostname: os.hostname(),
+        pid: process.pid,
+        platform: os.platform(),
+        arch: os.arch(),
+        memory: {
+            rss: memoryUsage.rss,
+            heapTotal: memoryUsage.heapTotal,
+            heapUsed: memoryUsage.heapUsed,
+            external: memoryUsage.external,
+            freeMem: os.freemem(),
+            totalMem: os.totalmem()
+        },
+        loadavg: os.loadavg(),
+        uptime: Math.round(process.uptime())
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { VantaTraceOptions, VantaTraceContext } from './types';
+export declare class VantaTrace {
+    private apiKey;
+    private serviceName;
+    private environment;
+    private debug;
+    private apiUrl;
+    constructor(options: VantaTraceOptions);
+    /**
+     * Primary method to capture exceptions and send them to VantaTrace
+     */
+    captureException(error: any, context?: VantaTraceContext): void;
+    /**
+     * Helper method to capture critical errors
+     */
+    captureCritical(error: any, context?: Omit<VantaTraceContext, 'severity'>): void;
+    /**
+     * Helper method to capture warning errors
+     */
+    captureWarning(error: any, context?: Omit<VantaTraceContext, 'severity'>): void;
+    /**
+     * Helper method to capture info messages/errors
+     */
+    captureInfo(error: any, context?: Omit<VantaTraceContext, 'severity'>): void;
+    /**
+     * Express error handling middleware
+     */
+    expressMiddleware(): (err: any, req: any, res: any, next: any) => void;
+    /**
+     * Automatically catch all uncaught exceptions and unhandled rejections
+     */
+    initGlobalHandlers(): void;
+}
+export default VantaTrace;

package/dist/index.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VantaTrace = void 0;
+const normalizer_1 = require("./normalizer");
+const context_1 = require("./context");
+const transport_1 = require("./transport");
+class VantaTrace {
+    constructor(options) {
+        this.apiKey = options.apiKey || '';
+        this.serviceName = options.serviceName || 'unknown-service';
+        let envInput = options.environment || process.env.NODE_ENV || 'development';
+        if (this.apiKey.includes('live')) {
+            envInput = 'live';
+        }
+        else if (this.apiKey.includes('test')) {
+            envInput = 'test';
+        }
+        this.environment = (envInput === 'production' || envInput === 'prod' || envInput === 'live') ? 'live' : 'test';
+        this.debug = !!options.debug;
+        // Default to localhost:6000/api/events (Standard Ingestion Endpoint)
+        this.apiUrl = options.apiUrl || 'https://api.vantatrace.com/api/events';
+        if (!options.apiKey && this.debug) {
+            console.warn('[VantaTrace] WARNING: API key is missing. SDK will run in dry-run mode.');
+        }
+        if (this.debug) {
+            console.log(`[VantaTrace] Initialized SDK for service "${this.serviceName}" on environment "${this.environment}".`);
+        }
+    }
+    /**
+     * Primary method to capture exceptions and send them to VantaTrace
+     */
+    captureException(error, context) {
+        try {
+            if (!this.apiKey) {
+                if (this.debug) {
+                    console.log('[VantaTrace] Dry-run: captured exception:', error, 'Context:', context);
+                }
+                return;
+            }
+            const normalized = (0, normalizer_1.normalizeError)(error);
+            const systemContext = (0, context_1.getSystemContext)();
+            const payload = {
+                apiKey: this.apiKey,
+                serviceName: this.serviceName,
+                environment: this.environment,
+                timestamp: new Date().toISOString(),
+                error: normalized,
+                context: context || {},
+                system: systemContext,
+                severity: context?.severity
+            };
+            if (this.debug) {
+                console.log(`[VantaTrace] Sending error event: ${normalized.name} - ${normalized.message} (Severity: ${payload.severity || 'default'})`);
+            }
+            (0, transport_1.sendPayload)(this.apiUrl, this.apiKey, payload, this.debug);
+        }
+        catch (e) {
+            if (this.debug) {
+                console.error(`[VantaTrace] Failed to capture exception internally: ${e.message}`);
+            }
+        }
+    }
+    /**
+     * Helper method to capture critical errors
+     */
+    captureCritical(error, context) {
+        this.captureException(error, { ...context, severity: 'critical' });
+    }
+    /**
+     * Helper method to capture warning errors
+     */
+    captureWarning(error, context) {
+        this.captureException(error, { ...context, severity: 'warning' });
+    }
+    /**
+     * Helper method to capture info messages/errors
+     */
+    captureInfo(error, context) {
+        this.captureException(error, { ...context, severity: 'info' });
+    }
+    /**
+     * Express error handling middleware
+     */
+    expressMiddleware() {
+        return (err, req, res, next) => {
+            let userId = undefined;
+            if (req.user && typeof req.user === 'object') {
+                userId = req.user.id || req.user._id || req.user.userId;
+            }
+            else if (req.userId) {
+                userId = req.userId;
+            }
+            // Sanitize request body if password exists
+            let sanitizedBody = undefined;
+            if (req.body && typeof req.body === 'object') {
+                sanitizedBody = { ...req.body };
+                if ('password' in sanitizedBody)
+                    sanitizedBody.password = '[REDACTED]';
+                if ('token' in sanitizedBody)
+                    sanitizedBody.token = '[REDACTED]';
+            }
+            // Extract client IP
+            const ip = req.ip || req.headers['x-forwarded-for'] || req.socket?.remoteAddress;
+            // Extract and sanitize headers
+            const sanitizedHeaders = {};
+            const sensitiveHeaderKeys = ['authorization', 'cookie', 'set-cookie', 'x-api-key', 'proxy-authorization'];
+            if (req.headers && typeof req.headers === 'object') {
+                for (const [key, value] of Object.entries(req.headers)) {
+                    if (sensitiveHeaderKeys.includes(key.toLowerCase())) {
+                        sanitizedHeaders[key] = '[REDACTED]';
+                    }
+                    else {
+                        sanitizedHeaders[key] = value;
+                    }
+                }
+            }
+            this.captureException(err, {
+                userId: userId ? String(userId) : undefined,
+                route: req.route?.path || req.path || req.url,
+                method: req.method,
+                ip: ip ? String(ip) : undefined,
+                headers: sanitizedHeaders,
+                metadata: {
+                    query: req.query,
+                    body: sanitizedBody
+                }
+            });
+            next(err);
+        };
+    }
+    /**
+     * Automatically catch all uncaught exceptions and unhandled rejections
+     */
+    initGlobalHandlers() {
+        process.on('uncaughtException', (err) => {
+            if (this.debug) {
+                console.log('[VantaTrace] Captured uncaught exception globally');
+            }
+            this.captureException(err);
+            // Let the exception bubble up to avoid inconsistent process state (standard practice)
+            // but give a short time window for the async request to finish sending.
+            setTimeout(() => {
+                process.exit(1);
+            }, 500);
+        });
+        process.on('unhandledRejection', (reason) => {
+            if (this.debug) {
+                console.log('[VantaTrace] Captured unhandled promise rejection globally');
+            }
+            const err = reason instanceof Error ? reason : new Error(String(reason));
+            this.captureException(err);
+        });
+    }
+}
+exports.VantaTrace = VantaTrace;
+exports.default = VantaTrace;

package/dist/normalizer.d.ts

@@ -0,0 +1,10 @@
+export declare function getFingerprint(name: string, message: string, stack: string): string;
+export declare function normalizeError(err: any): {
+    name: string;
+    message: string;
+    stack: string;
+    fingerprint: string;
+    code?: string;
+    statusCode?: number;
+    extra?: Record<string, any>;
+};

package/dist/normalizer.js

@@ -0,0 +1,103 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFingerprint = getFingerprint;
+exports.normalizeError = normalizeError;
+const crypto = __importStar(require("crypto"));
+function getFingerprint(name, message, stack) {
+    const hash = crypto.createHash('md5');
+    // Group by name, message, and the first 3 lines of the stack trace to ignore line number variations deep in libraries
+    const cleanStack = (stack || '')
+        .split('\n')
+        .slice(0, 4)
+        .map(line => line.trim())
+        .join('\n');
+    hash.update(`${name}:${message}:${cleanStack}`);
+    return hash.digest('hex');
+}
+function normalizeError(err) {
+    let name = 'Error';
+    let message = 'Unknown error';
+    let stack = '';
+    let code = undefined;
+    let statusCode = undefined;
+    let extra = undefined;
+    if (err instanceof Error) {
+        name = err.name || 'Error';
+        message = err.message || 'Unknown error';
+        stack = err.stack || '';
+        if ('code' in err)
+            code = String(err.code);
+        if ('status' in err)
+            statusCode = Number(err.status);
+        if ('statusCode' in err)
+            statusCode = Number(err.statusCode);
+        const extraKeys = Object.keys(err).filter(k => !['name', 'message', 'stack', 'code', 'status', 'statusCode'].includes(k));
+        if (extraKeys.length > 0) {
+            extra = {};
+            for (const key of extraKeys) {
+                extra[key] = err[key];
+            }
+        }
+    }
+    else if (typeof err === 'string') {
+        message = err;
+        stack = new Error(err).stack || '';
+    }
+    else if (err && typeof err === 'object') {
+        name = err.name || err.constructor?.name || 'Error';
+        message = err.message || JSON.stringify(err);
+        stack = err.stack || new Error(message).stack || '';
+        if ('code' in err)
+            code = String(err.code);
+        if ('status' in err)
+            statusCode = Number(err.status);
+        if ('statusCode' in err)
+            statusCode = Number(err.statusCode);
+        const extraKeys = Object.keys(err).filter(k => !['name', 'message', 'stack', 'code', 'status', 'statusCode'].includes(k));
+        if (extraKeys.length > 0) {
+            extra = {};
+            for (const key of extraKeys) {
+                extra[key] = err[key];
+            }
+        }
+    }
+    else {
+        message = String(err);
+        stack = new Error(message).stack || '';
+    }
+    const fingerprint = getFingerprint(name, message, stack);
+    return { name, message, stack, fingerprint, code, statusCode, extra };
+}

package/dist/transport.d.ts

@@ -0,0 +1,2 @@
+import { ErrorPayload } from './types';
+export declare function sendPayload(apiUrl: string, apiKey: string, payload: ErrorPayload, debug?: boolean, retriesRemaining?: number): void;

package/dist/transport.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendPayload = sendPayload;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const url_1 = require("url");
+function sendPayload(apiUrl, apiKey, payload, debug = false, retriesRemaining = 1) {
+    const logDebug = (msg) => {
+        if (debug) {
+            console.log(`[VantaTrace] ${msg}`);
+        }
+    };
+    // Run asynchronously to ensure we don't block the caller
+    process.nextTick(() => {
+        try {
+            const parsedUrl = new url_1.URL(apiUrl);
+            const postData = JSON.stringify(payload);
+            const options = {
+                hostname: parsedUrl.hostname,
+                port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+                path: parsedUrl.pathname + parsedUrl.search,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(postData),
+                    'x-api-key': apiKey
+                },
+                timeout: 300 // 300ms max timeout
+            };
+            const client = parsedUrl.protocol === 'https:' ? https : http;
+            const req = client.request(options, (res) => {
+                // Consume response data to prevent resource leaks
+                res.on('data', () => { });
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        logDebug('Event sent successfully');
+                    }
+                    else {
+                        logDebug(`Failed to send event. Status: ${res.statusCode}`);
+                        handleRetry();
+                    }
+                });
+            });
+            const handleRetry = () => {
+                if (retriesRemaining > 0) {
+                    logDebug(`Retry attempt ${2 - retriesRemaining}`);
+                    sendPayload(apiUrl, apiKey, payload, debug, retriesRemaining - 1);
+                }
+            };
+            req.on('error', (err) => {
+                logDebug(`Request error: ${err.message}`);
+                handleRetry();
+            });
+            req.on('timeout', () => {
+                logDebug('Timeout reached, aborting request');
+                req.destroy();
+            });
+            req.write(postData);
+            req.end();
+        }
+        catch (err) {
+            logDebug(`Transport execution failed: ${err.message}`);
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export interface VantaTraceOptions {
+    apiKey: string;
+    serviceName: string;
+    environment?: string;
+    debug?: boolean;
+    apiUrl?: string;
+}
+export interface VantaTraceContext {
+    userId?: string;
+    route?: string;
+    method?: string;
+    ip?: string;
+    headers?: Record<string, any>;
+    metadata?: Record<string, any>;
+    severity?: 'critical' | 'warning' | 'info';
+}
+export interface ErrorPayload {
+    apiKey: string;
+    serviceName: string;
+    environment: string;
+    timestamp: string;
+    error: {
+        message: string;
+        stack: string;
+        name: string;
+        fingerprint: string;
+        code?: string;
+        statusCode?: number;
+        extra?: Record<string, any>;
+    };
+    context: VantaTraceContext;
+    system: {
+        nodeVersion: string;
+        hostname: string;
+        pid: number;
+        platform: string;
+        arch: string;
+        memory: {
+            rss: number;
+            heapTotal: number;
+            heapUsed: number;
+            external?: number;
+            freeMem: number;
+            totalMem: number;
+        };
+        loadavg: number[];
+        uptime: number;
+    };
+    severity?: 'critical' | 'warning' | 'info';
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@vantatrace/sdk",
+  "version": "0.1.0",
+  "description": "Drop-in observability SDK for Node.js microservices powering error tracking, structured logging, and real-time telemetry pipelines.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "observability",
+    "error-tracking",
+    "logging",
+    "telemetry",
+    "nodejs",
+    "microservices",
+    "monitoring",
+    "crash-reporting",
+    "exception-handling",
+    "debugging",
+    "apm",
+    "distributed-systems",
+    "vantatrace"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Iqrarijaz/vantatrace_sdk.git"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  }
+}

package/src/context.ts

@@ -0,0 +1,22 @@
+import * as os from 'os';
+
+export function getSystemContext() {
+  const memoryUsage = process.memoryUsage();
+  return {
+    nodeVersion: process.version,
+    hostname: os.hostname(),
+    pid: process.pid,
+    platform: os.platform(),
+    arch: os.arch(),
+    memory: {
+      rss: memoryUsage.rss,
+      heapTotal: memoryUsage.heapTotal,
+      heapUsed: memoryUsage.heapUsed,
+      external: memoryUsage.external,
+      freeMem: os.freemem(),
+      totalMem: os.totalmem()
+    },
+    loadavg: os.loadavg(),
+    uptime: Math.round(process.uptime())
+  };
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+import { VantaTraceOptions, VantaTraceContext, ErrorPayload } from './types';
+import { normalizeError } from './normalizer';
+import { getSystemContext } from './context';
+import { sendPayload } from './transport';
+
+export class VantaTrace {
+  private apiKey: string;
+  private serviceName: string;
+  private environment: string;
+  private debug: boolean;
+  private apiUrl: string;
+
+  constructor(options: VantaTraceOptions) {
+    this.apiKey = options.apiKey || '';
+    this.serviceName = options.serviceName || 'unknown-service';
+
+    let envInput = options.environment || process.env.NODE_ENV || 'development';
+    if (this.apiKey.includes('live')) {
+      envInput = 'live';
+    } else if (this.apiKey.includes('test')) {
+      envInput = 'test';
+    }
+
+    this.environment = (envInput === 'production' || envInput === 'prod' || envInput === 'live') ? 'live' : 'test';
+    this.debug = !!options.debug;
+
+    // Default to localhost:6000/api/events (Standard Ingestion Endpoint)
+    this.apiUrl = options.apiUrl || 'https://api.vantatrace.com/api/events';
+
+    if (!options.apiKey && this.debug) {
+      console.warn('[VantaTrace] WARNING: API key is missing. SDK will run in dry-run mode.');
+    }
+
+    if (this.debug) {
+      console.log(`[VantaTrace] Initialized SDK for service "${this.serviceName}" on environment "${this.environment}".`);
+    }
+  }
+
+  /**
+   * Primary method to capture exceptions and send them to VantaTrace
+   */
+  public captureException(error: any, context?: VantaTraceContext): void {
+    try {
+      if (!this.apiKey) {
+        if (this.debug) {
+          console.log('[VantaTrace] Dry-run: captured exception:', error, 'Context:', context);
+        }
+        return;
+      }
+
+      const normalized = normalizeError(error);
+      const systemContext = getSystemContext();
+
+      const payload: ErrorPayload = {
+        apiKey: this.apiKey,
+        serviceName: this.serviceName,
+        environment: this.environment,
+        timestamp: new Date().toISOString(),
+        error: normalized,
+        context: context || {},
+        system: systemContext,
+        severity: context?.severity
+      };
+
+      if (this.debug) {
+        console.log(`[VantaTrace] Sending error event: ${normalized.name} - ${normalized.message} (Severity: ${payload.severity || 'default'})`);
+      }
+
+      sendPayload(this.apiUrl, this.apiKey, payload, this.debug);
+    } catch (e: any) {
+      if (this.debug) {
+        console.error(`[VantaTrace] Failed to capture exception internally: ${e.message}`);
+      }
+    }
+  }
+
+  /**
+   * Helper method to capture critical errors
+   */
+  public captureCritical(error: any, context?: Omit<VantaTraceContext, 'severity'>): void {
+    this.captureException(error, { ...context, severity: 'critical' });
+  }
+
+  /**
+   * Helper method to capture warning errors
+   */
+  public captureWarning(error: any, context?: Omit<VantaTraceContext, 'severity'>): void {
+    this.captureException(error, { ...context, severity: 'warning' });
+  }
+
+  /**
+   * Helper method to capture info messages/errors
+   */
+  public captureInfo(error: any, context?: Omit<VantaTraceContext, 'severity'>): void {
+    this.captureException(error, { ...context, severity: 'info' });
+  }
+
+  /**
+   * Express error handling middleware
+   */
+  public expressMiddleware() {
+    return (err: any, req: any, res: any, next: any) => {
+      let userId = undefined;
+      if (req.user && typeof req.user === 'object') {
+        userId = req.user.id || req.user._id || req.user.userId;
+      } else if (req.userId) {
+        userId = req.userId;
+      }
+
+      // Sanitize request body if password exists
+      let sanitizedBody = undefined;
+      if (req.body && typeof req.body === 'object') {
+        sanitizedBody = { ...req.body };
+        if ('password' in sanitizedBody) sanitizedBody.password = '[REDACTED]';
+        if ('token' in sanitizedBody) sanitizedBody.token = '[REDACTED]';
+      }
+
+      // Extract client IP
+      const ip = req.ip || (req.headers['x-forwarded-for'] as string) || req.socket?.remoteAddress;
+
+      // Extract and sanitize headers
+      const sanitizedHeaders: Record<string, any> = {};
+      const sensitiveHeaderKeys = ['authorization', 'cookie', 'set-cookie', 'x-api-key', 'proxy-authorization'];
+      if (req.headers && typeof req.headers === 'object') {
+        for (const [key, value] of Object.entries(req.headers)) {
+          if (sensitiveHeaderKeys.includes(key.toLowerCase())) {
+            sanitizedHeaders[key] = '[REDACTED]';
+          } else {
+            sanitizedHeaders[key] = value;
+          }
+        }
+      }
+
+      this.captureException(err, {
+        userId: userId ? String(userId) : undefined,
+        route: req.route?.path || req.path || req.url,
+        method: req.method,
+        ip: ip ? String(ip) : undefined,
+        headers: sanitizedHeaders,
+        metadata: {
+          query: req.query,
+          body: sanitizedBody
+        }
+      });
+      next(err);
+    };
+  }
+
+  /**
+   * Automatically catch all uncaught exceptions and unhandled rejections
+   */
+  public initGlobalHandlers(): void {
+    process.on('uncaughtException', (err) => {
+      if (this.debug) {
+        console.log('[VantaTrace] Captured uncaught exception globally');
+      }
+      this.captureException(err);
+
+      // Let the exception bubble up to avoid inconsistent process state (standard practice)
+      // but give a short time window for the async request to finish sending.
+      setTimeout(() => {
+        process.exit(1);
+      }, 500);
+    });
+
+    process.on('unhandledRejection', (reason) => {
+      if (this.debug) {
+        console.log('[VantaTrace] Captured unhandled promise rejection globally');
+      }
+      const err = reason instanceof Error ? reason : new Error(String(reason));
+      this.captureException(err);
+    });
+  }
+}
+export default VantaTrace;

package/src/normalizer.ts

@@ -0,0 +1,74 @@
+import * as crypto from 'crypto';
+
+export function getFingerprint(name: string, message: string, stack: string): string {
+  const hash = crypto.createHash('md5');
+  // Group by name, message, and the first 3 lines of the stack trace to ignore line number variations deep in libraries
+  const cleanStack = (stack || '')
+    .split('\n')
+    .slice(0, 4)
+    .map(line => line.trim())
+    .join('\n');
+  hash.update(`${name}:${message}:${cleanStack}`);
+  return hash.digest('hex');
+}
+
+export function normalizeError(err: any): {
+  name: string;
+  message: string;
+  stack: string;
+  fingerprint: string;
+  code?: string;
+  statusCode?: number;
+  extra?: Record<string, any>;
+} {
+  let name = 'Error';
+  let message = 'Unknown error';
+  let stack = '';
+  let code: string | undefined = undefined;
+  let statusCode: number | undefined = undefined;
+  let extra: Record<string, any> | undefined = undefined;
+
+  if (err instanceof Error) {
+    name = err.name || 'Error';
+    message = err.message || 'Unknown error';
+    stack = err.stack || '';
+    
+    if ('code' in err) code = String((err as any).code);
+    if ('status' in err) statusCode = Number((err as any).status);
+    if ('statusCode' in err) statusCode = Number((err as any).statusCode);
+
+    const extraKeys = Object.keys(err).filter(k => !['name', 'message', 'stack', 'code', 'status', 'statusCode'].includes(k));
+    if (extraKeys.length > 0) {
+      extra = {};
+      for (const key of extraKeys) {
+        extra[key] = (err as any)[key];
+      }
+    }
+  } else if (typeof err === 'string') {
+    message = err;
+    stack = new Error(err).stack || '';
+  } else if (err && typeof err === 'object') {
+    name = err.name || err.constructor?.name || 'Error';
+    message = err.message || JSON.stringify(err);
+    stack = err.stack || new Error(message).stack || '';
+
+    if ('code' in err) code = String(err.code);
+    if ('status' in err) statusCode = Number(err.status);
+    if ('statusCode' in err) statusCode = Number(err.statusCode);
+
+    const extraKeys = Object.keys(err).filter(k => !['name', 'message', 'stack', 'code', 'status', 'statusCode'].includes(k));
+    if (extraKeys.length > 0) {
+      extra = {};
+      for (const key of extraKeys) {
+        extra[key] = err[key];
+      }
+    }
+  } else {
+    message = String(err);
+    stack = new Error(message).stack || '';
+  }
+
+  const fingerprint = getFingerprint(name, message, stack);
+
+  return { name, message, stack, fingerprint, code, statusCode, extra };
+}

package/src/transport.ts

@@ -0,0 +1,76 @@
+import * as http from 'http';
+import * as https from 'https';
+import { URL } from 'url';
+import { ErrorPayload } from './types';
+
+export function sendPayload(
+  apiUrl: string,
+  apiKey: string,
+  payload: ErrorPayload,
+  debug: boolean = false,
+  retriesRemaining: number = 1
+): void {
+  const logDebug = (msg: string) => {
+    if (debug) {
+      console.log(`[VantaTrace] ${msg}`);
+    }
+  };
+
+  // Run asynchronously to ensure we don't block the caller
+  process.nextTick(() => {
+    try {
+      const parsedUrl = new URL(apiUrl);
+      const postData = JSON.stringify(payload);
+      
+      const options: http.RequestOptions | https.RequestOptions = {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+        path: parsedUrl.pathname + parsedUrl.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(postData),
+          'x-api-key': apiKey
+        },
+        timeout: 300 // 300ms max timeout
+      };
+
+      const client = parsedUrl.protocol === 'https:' ? https : http;
+
+      const req = client.request(options, (res) => {
+        // Consume response data to prevent resource leaks
+        res.on('data', () => {});
+        res.on('end', () => {
+          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+            logDebug('Event sent successfully');
+          } else {
+            logDebug(`Failed to send event. Status: ${res.statusCode}`);
+            handleRetry();
+          }
+        });
+      });
+
+      const handleRetry = () => {
+        if (retriesRemaining > 0) {
+          logDebug(`Retry attempt ${2 - retriesRemaining}`);
+          sendPayload(apiUrl, apiKey, payload, debug, retriesRemaining - 1);
+        }
+      };
+
+      req.on('error', (err) => {
+        logDebug(`Request error: ${err.message}`);
+        handleRetry();
+      });
+
+      req.on('timeout', () => {
+        logDebug('Timeout reached, aborting request');
+        req.destroy();
+      });
+
+      req.write(postData);
+      req.end();
+    } catch (err: any) {
+      logDebug(`Transport execution failed: ${err.message}`);
+    }
+  });
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+export interface VantaTraceOptions {
+  apiKey: string;
+  serviceName: string;
+  environment?: string;
+  debug?: boolean;
+  apiUrl?: string;
+}
+
+export interface VantaTraceContext {
+  userId?: string;
+  route?: string;
+  method?: string;
+  ip?: string;
+  headers?: Record<string, any>;
+  metadata?: Record<string, any>;
+  severity?: 'critical' | 'warning' | 'info';
+}
+
+export interface ErrorPayload {
+  apiKey: string;
+  serviceName: string;
+  environment: string;
+  timestamp: string;
+  error: {
+    message: string;
+    stack: string;
+    name: string;
+    fingerprint: string;
+    code?: string;
+    statusCode?: number;
+    extra?: Record<string, any>;
+  };
+  context: VantaTraceContext;
+  system: {
+    nodeVersion: string;
+    hostname: string;
+    pid: number;
+    platform: string;
+    arch: string;
+    memory: {
+      rss: number;
+      heapTotal: number;
+      heapUsed: number;
+      external?: number;
+      freeMem: number;
+      totalMem: number;
+    };
+    loadavg: number[];
+    uptime: number;
+  };
+  severity?: 'critical' | 'warning' | 'info';
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["es2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}