kohi-node 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -3,7 +3,6 @@
 import { IncomingMessage, ServerResponse } from 'http';
 import { gzip } from 'zlib';
 
-export declare const VERSION = "node:0.1.2";
 export declare const DEFAULT_INGEST_ENDPOINT = "https://kohicorp.com/api/ingest";
 export declare const DEFAULT_MAX_CONCURRENT_SENDS = 5;
 export declare const DEFAULT_QUEUE_SIZE = 5000;
@@ -76,16 +75,78 @@ export declare class Monitor {
 	addEvent(evt: Event$1): void;
 	shutdown(): Promise<void>;
 	close(): Promise<void>;
+	captureException(error: Error, opts?: {
+		fingerprint?: string;
+	}): void;
+	captureExceptionWithRequest(error: Error, reqURL: string, reqMethod: string, clientIP?: string): void;
+	captureMessage(msg: string, level?: "fatal" | "error" | "warning"): void;
+	captureHttpError(statusCode: number, responseBody: string, reqURL: string, reqMethod: string, clientIP?: string): void;
+	private enqueue;
 	private startWorker;
 	private sendBatch;
 	private sendBatchAttempt;
 }
 export declare function createMonitor(config: Config): Monitor;
+export interface StackFrame {
+	file: string;
+	line: number;
+	column?: number;
+	function: string;
+	context?: string[];
+	in_app: boolean;
+}
+export interface ErrorEvent {
+	_type: "error";
+	error_type: string;
+	error_message: string;
+	level: "fatal" | "error" | "warning";
+	fingerprint?: string;
+	stack_frames: StackFrame[];
+	request_url?: string;
+	request_method?: string;
+	timestamp: number;
+	client_ip?: string;
+}
+export declare function parseNodeStack(stack: string): StackFrame[];
+declare let _monitorRef: {
+	captureException(err: Error): void;
+	captureExceptionWithRequest(err: Error, url: string, method: string, clientIP?: string): void;
+	isEnabled(): boolean;
+} | null;
+/**
+ * Installs process-level error handlers for uncaught exceptions and unhandled
+ * rejections. Captured errors are queued for the next batch send.
+ *
+ * Uses AsyncLocalStorage to propagate request context — async errors thrown
+ * inside request handlers are captured with the originating URL and method.
+ *
+ * NOTE: Adding an `uncaughtException` listener prevents Node.js from
+ * terminating the process on unhandled exceptions. If your application relies
+ * on crash-and-restart behavior (e.g., with PM2 or systemd), you should still
+ * call `process.exit(1)` in your own `uncaughtException` handler after the
+ * Kohi handler runs.
+ */
+export declare function installGlobalHooks(monitor: typeof _monitorRef): void;
 export declare function expressMiddleware(monitor: Monitor): (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+export declare function expressErrorHandler(monitor: Monitor): (err: Error, req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
 export declare function instrumentNextJs(cfg: Config): void;
+/**
+ * Next.js onRequestError handler for instrumentation.ts.
+ * Usage in instrumentation.ts:
+ *   import { onRequestError } from '@kohi/node';
+ *   export { onRequestError };
+ */
+export declare function onRequestError(err: {
+	digest: string;
+} & Error, request: {
+	path: string;
+	method: string;
+	headers: Record<string, string | string[]>;
+}, _context: unknown): void;
 export declare function init(cfg: Config): {
 	monitor: Monitor;
 	expressMiddleware: () => (req: import("http").IncomingMessage, res: import("http").ServerResponse, next: () => void) => void;
+	expressErrorHandler: () => (err: Error, req: import("http").IncomingMessage, res: import("http").ServerResponse, next: (err?: unknown) => void) => void;
 	instrumentNextJs: () => void;
 };
 declare const defaultExport: typeof Monitor & {

package/dist/index.js

@@ -37,22 +37,25 @@ __export(index_exports, {
   Monitor: () => Monitor,
   REDACTION_MASK: () => REDACTION_MASK,
   SENSITIVE_KEYS: () => SENSITIVE_KEYS,
-  VERSION: () => VERSION,
   canonicalHeaders: () => canonicalHeaders,
   createMonitor: () => createMonitor,
   default: () => index_default,
+  expressErrorHandler: () => expressErrorHandler,
   expressMiddleware: () => expressMiddleware,
   extractClientIP: () => extractClientIP,
   firstIPFromList: () => firstIPFromList,
   gzipAsync: () => gzipAsync,
   init: () => init,
+  installGlobalHooks: () => installGlobalHooks,
   instrumentNextJs: () => instrumentNextJs,
   isRetryableStatus: () => isRetryableStatus,
   isValidIP: () => isValidIP,
   jitter: () => jitter,
   normalizeIP: () => normalizeIP,
+  onRequestError: () => onRequestError,
   parseForwardedHeader: () => parseForwardedHeader,
   parseJSONBody: () => parseJSONBody,
+  parseNodeStack: () => parseNodeStack,
   peerIPFromRemoteAddr: () => peerIPFromRemoteAddr,
   redactEvent: () => redactEvent,
   redactHeaders: () => redactHeaders,
@@ -67,8 +70,8 @@ module.exports = __toCommonJS(index_exports);
 var import_crypto = require("crypto");
 var import_zlib = require("zlib");
 var import_util = require("util");
-var VERSION = "node:0.1.2";
 var DEFAULT_INGEST_ENDPOINT = "https://kohicorp.com/api/ingest";
+var MAX_REQUEST_BODY = 64 * 1024;
 var MAX_RESPONSE_BODY = 64 * 1024;
 var DEFAULT_MAX_CONCURRENT_SENDS = 5;
 var DEFAULT_QUEUE_SIZE = 5e3;
@@ -190,6 +193,70 @@ function parseJSONBody(raw) {
   }
 }
 
+// src/errors.ts
+var import_node_async_hooks = require("node:async_hooks");
+function parseNodeStack(stack) {
+  const frames = [];
+  for (const line of stack.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("at ")) continue;
+    const frame = parseStackLine(trimmed.slice(3));
+    if (frame) frames.push(frame);
+  }
+  return frames;
+}
+function parseStackLine(line) {
+  const parenMatch = line.match(/^(.+?)\s+\((.+):(\d+):(\d+)\)$/);
+  if (parenMatch) {
+    return { function: parenMatch[1], file: parenMatch[2], line: +parenMatch[3], column: +parenMatch[4], in_app: isInApp(parenMatch[2]) };
+  }
+  const anonMatch = line.match(/^(.+):(\d+):(\d+)$/);
+  if (anonMatch) {
+    return { function: "<anonymous>", file: anonMatch[1], line: +anonMatch[2], column: +anonMatch[3], in_app: isInApp(anonMatch[1]) };
+  }
+  return null;
+}
+function isInApp(file) {
+  return !file.includes("node_modules/") && !file.includes("node_modules\\") && !file.startsWith("node:") && !file.startsWith("internal/");
+}
+function buildErrorEvent(err, level = "error", reqURL, reqMethod, clientIP) {
+  const evt = {
+    _type: "error",
+    error_type: err.constructor?.name ?? "Error",
+    error_message: err.message,
+    level,
+    stack_frames: err.stack ? parseNodeStack(err.stack) : [],
+    request_url: reqURL,
+    request_method: reqMethod,
+    timestamp: Date.now()
+  };
+  if (clientIP) evt.client_ip = clientIP;
+  return evt;
+}
+var requestContext = new import_node_async_hooks.AsyncLocalStorage();
+var _hooksInstalled = false;
+var _monitorRef = null;
+function installGlobalHooks(monitor) {
+  _monitorRef = monitor;
+  if (_hooksInstalled) return;
+  _hooksInstalled = true;
+  const capture = (raw) => {
+    if (!_monitorRef?.isEnabled()) return;
+    const error = raw instanceof Error ? raw : new Error(String(raw));
+    const reqCtx = requestContext.getStore();
+    try {
+      if (reqCtx) {
+        _monitorRef.captureExceptionWithRequest(error, reqCtx.url, reqCtx.method, reqCtx.clientIP);
+      } else {
+        _monitorRef.captureException(error);
+      }
+    } catch {
+    }
+  };
+  process.on("uncaughtException", capture);
+  process.on("unhandledRejection", capture);
+}
+
 // src/monitor.ts
 var Monitor = class _Monitor {
   projectKey;
@@ -218,7 +285,10 @@ var Monitor = class _Monitor {
     this.secret = Buffer.from(config.secretKey, "base64url");
     this.logger = config.logger ?? noopLogger;
     this.enabled = enabled;
-    if (this.enabled) this.startWorker();
+    if (this.enabled) {
+      this.startWorker();
+      installGlobalHooks(this);
+    }
   }
   static noop() {
     return new _Monitor({ projectKey: "pk_00000000000000000000AA", secretKey: "0000000000000000000000000000000000000000000", enabled: false });
@@ -229,11 +299,7 @@ var Monitor = class _Monitor {
   addEvent(evt) {
     if (!this.enabled || this.closed) return;
     const normalized = { ...evt, method: evt.method.toUpperCase(), request_headers: canonicalHeaders(evt.request_headers), response_headers: canonicalHeaders(evt.response_headers) };
-    if (this.queue.length >= this.queueSize) {
-      this.logger.warn("kohi monitor queue is full; dropping event");
-      return;
-    }
-    this.queue.push(normalized);
+    this.enqueue(normalized);
   }
   async shutdown() {
     if (this.closed) return;
@@ -244,6 +310,51 @@ var Monitor = class _Monitor {
   async close() {
     return this.shutdown();
   }
+  captureException(error, opts) {
+    if (!this.enabled || this.closed) return;
+    const evt = buildErrorEvent(error, "error");
+    if (opts?.fingerprint) evt.fingerprint = opts.fingerprint;
+    this.enqueue(evt);
+  }
+  captureExceptionWithRequest(error, reqURL, reqMethod, clientIP) {
+    if (!this.enabled || this.closed) return;
+    const evt = buildErrorEvent(error, "error", reqURL, reqMethod, clientIP);
+    this.enqueue(evt);
+  }
+  captureMessage(msg, level = "error") {
+    if (!this.enabled || this.closed) return;
+    const evt = {
+      _type: "error",
+      error_type: "Message",
+      error_message: msg,
+      level,
+      stack_frames: [],
+      timestamp: Date.now()
+    };
+    this.enqueue(evt);
+  }
+  captureHttpError(statusCode, responseBody, reqURL, reqMethod, clientIP) {
+    if (!this.enabled || this.closed) return;
+    const evt = {
+      _type: "error",
+      error_type: `HTTP ${statusCode}`,
+      error_message: responseBody,
+      level: "error",
+      stack_frames: [],
+      request_url: reqURL,
+      request_method: reqMethod,
+      timestamp: Date.now()
+    };
+    if (clientIP) evt.client_ip = clientIP;
+    this.enqueue(evt);
+  }
+  enqueue(evt) {
+    if (this.queue.length >= this.queueSize) {
+      this.logger.warn("kohi monitor queue is full; dropping event");
+      return;
+    }
+    this.queue.push(evt);
+  }
   startWorker() {
     const tick = async () => {
       let lastFlush = Date.now();
@@ -266,7 +377,7 @@ var Monitor = class _Monitor {
     tick().catch((err) => this.logger.error(`kohi: worker fatal: ${err}`));
   }
   async sendBatch(events) {
-    const redacted = events.map(redactEvent);
+    const redacted = events.map((e) => "_type" in e && e._type === "error" ? e : redactEvent(e));
     let payload;
     try {
       payload = await gzipAsync(Buffer.from(JSON.stringify(redacted), "utf8"));
@@ -325,9 +436,24 @@ function expressMiddleware(monitor) {
       return;
     }
     const start = Date.now();
+    const reqURL = req.url ?? "/";
+    const reqMethod = (req.method ?? "GET").toUpperCase();
+    const reqHeaders = canonicalHeaders(req.headers);
+    const peerIP = peerIPFromRemoteAddr(req.socket?.remoteAddress ?? "");
+    const clientIP = extractClientIP(reqHeaders, peerIP);
     const chunks = [], resChunks = [];
-    let reqBodyBuf = Buffer.alloc(0), totalRes = 0, capped = false, reqBodyReady = false, sent = false;
-    req.on("data", (c) => chunks.push(c));
+    let reqBodyBuf = Buffer.alloc(0), totalReq = 0, totalRes = 0, capped = false, reqCapped = false, reqBodyReady = false, sent = false, errorCaptured = false;
+    req.on("data", (c) => {
+      if (reqCapped) return;
+      const rem = MAX_REQUEST_BODY - totalReq;
+      if (rem <= 0) {
+        reqCapped = true;
+        return;
+      }
+      chunks.push(c.subarray(0, Math.min(c.length, rem)));
+      totalReq += Math.min(c.length, rem);
+      if (c.length > rem) reqCapped = true;
+    });
     req.once("end", () => {
       reqBodyBuf = Buffer.concat(chunks);
       reqBodyReady = true;
@@ -356,10 +482,6 @@ function expressMiddleware(monitor) {
     const finalize = () => {
       if (sent) return;
       sent = true;
-      const reqHeaders = canonicalHeaders(req.headers);
-      reqHeaders["x-kohi-version"] = VERSION;
-      const peerIP = peerIPFromRemoteAddr(req.socket?.remoteAddress ?? "");
-      const clientIP = extractClientIP(reqHeaders, peerIP);
       const status = res.statusCode || 200;
       let resBody = parseJSONBody(Buffer.concat(resChunks));
       if (status >= 500 && resChunks.length === 0) resBody = { error: res.statusMessage || "Internal Server Error" };
@@ -377,6 +499,11 @@ function expressMiddleware(monitor) {
         client_ip: clientIP
       };
       monitor.addEvent(evt);
+      if (status >= 500 && !errorCaptured && !res._kohiErrorCaptured) {
+        const body = Buffer.concat(resChunks).toString("utf8").trim();
+        const msg = body.slice(0, 256) || res.statusMessage || "Internal Server Error";
+        monitor.captureHttpError(status, msg, reqURL, reqMethod, clientIP);
+      }
     };
     const fail = (err) => {
       if (sent) return;
@@ -388,18 +515,34 @@ function expressMiddleware(monitor) {
     res.on("finish", finalize);
     res.on("close", finalize);
     res.on("error", fail);
-    try {
-      next();
-    } catch (err) {
-      fail(err);
-      throw err;
+    requestContext.run({ url: reqURL, method: reqMethod, clientIP }, () => {
+      try {
+        next();
+      } catch (err) {
+        errorCaptured = true;
+        const error = err instanceof Error ? err : new Error(String(err));
+        monitor.captureExceptionWithRequest(error, reqURL, reqMethod, clientIP);
+        fail(err);
+        throw err;
+      }
+    });
+  };
+}
+function expressErrorHandler(monitor) {
+  return (err, req, res, next) => {
+    if (monitor.isEnabled()) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      const headers = canonicalHeaders(req.headers);
+      const ip = extractClientIP(headers, peerIPFromRemoteAddr(req.socket?.remoteAddress ?? ""));
+      monitor.captureExceptionWithRequest(error, req.url ?? "/", (req.method ?? "GET").toUpperCase(), ip);
+      res._kohiErrorCaptured = true;
     }
+    next(err);
   };
 }
 
 // src/integrations/nextjs.ts
 var http = __toESM(require("http"));
-var MAX_REQUEST_BODY = 64 * 1024;
 var sharedMonitor = null;
 var instrumented = false;
 var requestBodies = /* @__PURE__ */ new WeakMap();
@@ -435,7 +578,9 @@ function instrumentNextJs(cfg) {
         const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
         const remaining = MAX_REQUEST_BODY - bodyData.size;
         if (remaining > 0) {
-          bodyData.chunks.push(buf.subarray(0, Math.min(buf.length, remaining)));
+          bodyData.chunks.push(
+            buf.subarray(0, Math.min(buf.length, remaining))
+          );
           bodyData.size += Math.min(buf.length, remaining);
         }
       }
@@ -454,12 +599,14 @@ function instrumentNextJs(cfg) {
 function instrumentRequest(req, res) {
   if (!sharedMonitor) return;
   const url = req.url ?? "/";
-  if (url.startsWith("/_next") || url.startsWith("/__next") || url.includes("/_next/")) return;
+  if (url.startsWith("/_next") || url.startsWith("/__next") || url.includes("/_next/"))
+    return;
   if (!url.startsWith("/api/")) return;
   const start = Date.now();
   const method = req.method ?? "GET";
-  const reqHeaders = canonicalHeaders(req.headers);
-  reqHeaders["x-kohi-version"] = VERSION;
+  const reqHeaders = canonicalHeaders(
+    req.headers
+  );
   const peerIP = peerIPFromRemoteAddr(req.socket?.remoteAddress ?? "");
   const clientIP = extractClientIP(reqHeaders, peerIP);
   const captureState = { total: 0, capped: false };
@@ -485,7 +632,9 @@ function instrumentRequest(req, res) {
       status_code: res.statusCode,
       request_headers: reqHeaders,
       request_body: reqBody,
-      response_headers: canonicalHeaders(res.getHeaders()),
+      response_headers: canonicalHeaders(
+        res.getHeaders()
+      ),
       response_body: parseJSONBody(resBody),
       duration_ms: duration,
       client_ip: clientIP
@@ -494,6 +643,15 @@ function instrumentRequest(req, res) {
     return originalEnd(chunk, ...args);
   };
 }
+function onRequestError(err, request, _context) {
+  if (!sharedMonitor) return;
+  const error = err instanceof Error ? err : new Error(String(err));
+  const url = request?.path ?? "/";
+  const method = (request?.method ?? "GET").toUpperCase();
+  const headers = canonicalHeaders(request?.headers ?? {});
+  const clientIP = extractClientIP(headers, "");
+  sharedMonitor.captureExceptionWithRequest(error, url, method, clientIP);
+}
 
 // src/index.ts
 function init(cfg) {
@@ -501,6 +659,7 @@ function init(cfg) {
   return {
     monitor,
     expressMiddleware: () => expressMiddleware(monitor),
+    expressErrorHandler: () => expressErrorHandler(monitor),
     instrumentNextJs: () => instrumentNextJs(cfg)
   };
 }
@@ -515,21 +674,24 @@ var index_default = defaultExport;
   Monitor,
   REDACTION_MASK,
   SENSITIVE_KEYS,
-  VERSION,
   canonicalHeaders,
   createMonitor,
+  expressErrorHandler,
   expressMiddleware,
   extractClientIP,
   firstIPFromList,
   gzipAsync,
   init,
+  installGlobalHooks,
   instrumentNextJs,
   isRetryableStatus,
   isValidIP,
   jitter,
   normalizeIP,
+  onRequestError,
   parseForwardedHeader,
   parseJSONBody,
+  parseNodeStack,
   peerIPFromRemoteAddr,
   redactEvent,
   redactHeaders,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kohi-node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Kohi API monitoring SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,8 +16,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js && dts-bundle-generator -o dist/index.d.ts src/index.ts --no-check",
-    "test": "npx tsx --test tests/index.test.ts",
+    "build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js && dts-bundle-generator -o dist/index.d.ts src/index.ts --no-check --export-referenced-types=false",
+    "test": "npx tsx --test tests/index.test.ts tests/errors.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -27,15 +27,7 @@
     "kohi"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kohicorp/kohi",
-    "directory": "sdk/node"
-  },
   "homepage": "https://kohicorp.com",
-  "bugs": {
-    "url": "https://github.com/kohicorp/kohi/issues"
-  },
   "devDependencies": {
     "@types/node": "^20.19.30",
     "dts-bundle-generator": "^9.5.1",