@argusdev/sdk-node 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @argusdev/sdk-node
+
+Node.js SDK for [Argus](https://github.com/oluwatobicode/argus) — captures uncaught exceptions and unhandled rejections, with an optional Express error handler.
+
+## Install
+
+```bash
+npm install @argusdev/sdk-node
+```
+
+## Usage
+
+```ts
+import { init } from "@argusdev/sdk-node";
+
+init({ dsn: "https://<publicKey>@<host>/<projectId>", environment: "production" });
+```
+
+`process.on("uncaughtException")` and `process.on("unhandledRejection")` are wired automatically. On an uncaught exception the event is sent, then the process exits `1` (crash behavior preserved).
+
+### Express
+
+Add the error handler **after your routes**, before your own:
+
+```ts
+import { argusErrorHandler } from "@argusdev/sdk-node";
+
+app.use(argusErrorHandler());
+```
+
+It captures the error with request context, then passes it along — it observes, never absorbs.
+
+MIT © Treasure Odetokun

package/dist/express.d.ts

@@ -0,0 +1,7 @@
+interface RequestLike {
+    method?: string;
+    originalUrl?: string;
+    url?: string;
+}
+export declare function argusErrorHandler(): (err: unknown, req: RequestLike, _res: unknown, next: (err?: unknown) => void) => void;
+export {};

package/dist/express.js

@@ -0,0 +1,20 @@
+import { captureException } from "./init";
+/*
+ * Usage (LAST middleware, after routes):
+ *   app.use(argusErrorHandler());
+ *
+ * Captures the error with request context, then passes it along so the
+ * app's own error handler still responds to the user. We observe, never absorb.
+ */
+export function argusErrorHandler() {
+    return (err, req, _res, next) => {
+        void captureException(err, {
+            request: {
+                method: req.method,
+                url: req.originalUrl ?? req.url,
+            },
+        });
+        next(err);
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAS1C;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,GAAY,EACZ,GAAgB,EAChB,IAAa,EACb,IAA6B,EACvB,EAAE;QACR,KAAK,gBAAgB,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE;gBACP,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,GAAG,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG;aAChC;SACF,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { init, captureException } from "./init";
+export type { InitOptions } from "./init";
+export { argusErrorHandler } from "./express";
+export { parseStack } from "./stacktrace";

package/dist/index.js

@@ -0,0 +1,5 @@
+/* Public surface of @argusdev/sdk-node */
+export { init, captureException } from "./init";
+export { argusErrorHandler } from "./express";
+export { parseStack } from "./stacktrace";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAE1C,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,8 @@
+import { type EnvelopeOptions } from "@argusdev/sdk-core";
+export interface InitOptions {
+    dsn: string;
+    environment?: string;
+    release?: string;
+}
+export declare function init(options: InitOptions): void;
+export declare function captureException(err: unknown, extra?: EnvelopeOptions): Promise<void>;

package/dist/init.js

@@ -0,0 +1,39 @@
+import { parseDsn, getIngestUrl, buildEnvelope, sendEnvelope, } from "@argusdev/sdk-core";
+import { parseStack } from "./stacktrace";
+/* set once by init(); null means "not initialized — do nothing, never crash" */
+let client = null;
+export function init(options) {
+    const parsed = parseDsn(options.dsn); /* throws on bad DSN — loudly, at startup */
+    client = {
+        url: getIngestUrl(parsed),
+        publicKey: parsed.publicKey,
+        environment: options.environment,
+        release: options.release,
+    };
+    process.on("uncaughtException", (err) => {
+        /* capture, wait for the send, then exit non-zero — after an uncaught
+           exception the process state is untrustworthy; Node docs say exit. */
+        void captureException(err).finally(() => process.exit(1));
+    });
+    process.on("unhandledRejection", (reason) => {
+        void captureException(reason);
+    });
+}
+export async function captureException(err, extra = {}) {
+    if (!client)
+        return; /* init() not called — silently no-op */
+    /* people reject(non-Error) all the time — normalize */
+    const error = err instanceof Error ? err : new Error(String(err));
+    let frames = parseStack(error.stack);
+    if (frames.length === 0) {
+        /* validator requires >= 1 frame — synthesize one rather than drop the event */
+        frames = [{ filename: "<unknown>", lineno: 1 }];
+    }
+    const envelope = buildEnvelope(error.name, error.message, frames, {
+        environment: client.environment,
+        release: client.release,
+        ...extra,
+    });
+    await sendEnvelope(client.url, client.publicKey, envelope);
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,YAAY,GAEb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ1C,gFAAgF;AAChF,IAAI,MAAM,GAKC,IAAI,CAAC;AAEhB,MAAM,UAAU,IAAI,CAAC,OAAoB;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,4CAA4C;IAClF,MAAM,GAAG;QACP,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAU,EAAE,EAAE;QAC7C;+EACuE;QACvE,KAAK,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAe,EAAE,EAAE;QACnD,KAAK,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAY,EACZ,QAAyB,EAAE;IAE3B,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,wCAAwC;IAE7D,uDAAuD;IACvD,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAElE,IAAI,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,+EAA+E;QAC/E,MAAM,GAAG,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE;QAChE,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,GAAG,KAAK;KACT,CAAC,CAAC;IAEH,MAAM,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAC7D,CAAC"}

package/dist/stacktrace.d.ts

@@ -0,0 +1,2 @@
+import type { StackFrame } from "@argusdev/sdk-core";
+export declare function parseStack(stack: string | undefined): StackFrame[];

package/dist/stacktrace.js

@@ -0,0 +1,26 @@
+/* V8 stack lines come in two shapes:
+ *   at inner (/app/src/service.ts:42:17)   ← named
+ *   at /app/src/index.ts:7:3               ← anonymous
+ * One regex covers both: the "name (" part is optional.
+ */
+const FRAME_REGEX = /^at\s+(?:(.+?)\s+\()?(.+):(\d+):(\d+)\)?$/;
+export function parseStack(stack) {
+    if (!stack)
+        return [];
+    const frames = stack.split("\n").map((line) => {
+        const match = line.trim().match(FRAME_REGEX);
+        if (!match)
+            return null;
+        const frame = {
+            filename: match[2],
+            lineno: Number(match[3]),
+            colno: Number(match[4]),
+        };
+        if (match[1]) {
+            frame.function = match[1];
+        }
+        return frame;
+    });
+    return frames.filter((frame) => frame !== null);
+}
+//# sourceMappingURL=stacktrace.js.map

package/dist/stacktrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stacktrace.js","sourceRoot":"","sources":["../src/stacktrace.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,GAAG,2CAA2C,CAAC;AAEhE,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAqB,EAAE;QAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,KAAK,GAAe;YACxB,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAE;YACnB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACxB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACxB,CAAC;QACF,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACb,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAuB,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;AACvE,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@argusdev/sdk-node",
+  "version": "0.1.0",
+  "description": "Argus SDK for Node.js — uncaught exceptions, unhandled rejections, Express middleware.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@argusdev/sdk-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "~6.0.3"
+  },
+  "license": "MIT",
+  "author": "Treasure Odetokun",
+  "homepage": "https://github.com/oluwatobicode/argus#readme",
+  "keywords": [
+    "argus",
+    "error-tracking",
+    "monitoring",
+    "sdk",
+    "node",
+    "express"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oluwatobicode/argus.git",
+    "directory": "packages/sdk-node"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}