@forge-ops/tracker 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @forge-ops/tracker
+
+Node.js error reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
+Requires Node 18+ (for global `fetch`). A from-scratch port of
+[`gems/forge_ops_tracker`](../../gems/forge_ops_tracker) (the Rails client) -- see that gem's
+README for the shared design rationale; this document only covers what's Node-specific.
+
+## Installation
+
+Not yet published to npm -- install directly from this path (or a local checkout, once split into
+its own repo):
+
+```bash
+npm install /path/to/forge_ops/sdks/node
+```
+
+## Configuration
+
+Set a DSN (from a project's settings page in ForgeOps), either via the `FORGE_OPS_DSN` environment
+variable or explicitly:
+
+```js
+import * as forgeOpsTracker from "@forge-ops/tracker";
+
+forgeOpsTracker.init({
+  dsn: "https://<api_key>@your-forgeops-host/api/v1/events", // or leave unset to read FORGE_OPS_DSN
+  release: "...",
+  environment: "production",
+});
+```
+
+Call `init()` once at startup, before handling any requests. Any `Configuration` property can be
+overridden by passing it in the options object.
+
+### Express
+
+```js
+import { forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
+
+app.use(forgeOpsTrackerExpressMiddleware); // last, after all routes
+```
+
+Requires Express 5+ -- its automatic forwarding of both synchronous throws *and* rejected promises
+from `async` route handlers to error-handling middleware is what makes this work with zero other
+wiring (verified directly against a real async handler, not assumed). Express 4 does not do this
+for async handlers; each route would need its own try/catch there instead.
+
+### Fastify
+
+```js
+import { registerForgeOpsTracker } from "@forge-ops/tracker/integrations/fastify";
+
+registerForgeOpsTracker(app); // called directly, not via app.register()
+```
+
+Called directly on your Fastify instance rather than through `app.register()`, which would create
+a new encapsulation scope (and require the `fastify-plugin` package to break out of it) -- this
+avoids that entirely.
+
+## What gets reported automatically, and what doesn't
+
+**An exception that crashes a request needs no further wiring at all.** Both integrations above
+report anything that propagates uncaught out of a route handler, then let the framework handle it
+exactly as if this client weren't installed.
+
+**An exception your own code catches and handles is different -- neither integration ever sees
+it**, since it never propagates far enough to reach either hook:
+
+```js
+try {
+  await chargeCard(order);
+} catch (err) {
+  logger.warn(`card declined: ${err.message}`);
+  // ForgeOps never sees this -- caught locally, never reaches the
+  // middleware/hook at all.
+}
+```
+
+There's no Express/Fastify-wide equivalent to Rails' `Rails.error.handle` here -- report it
+explicitly instead, right at the catch site:
+
+```js
+} catch (err) {
+  forgeOpsTracker.captureException(err, { orderId: order.id });
+  logger.warn(`card declined: ${err.message}`);
+}
+```
+
+### Outside a web request (scripts, workers, unhandled promise rejections)
+
+`init()` also installs `process` event listeners by default (`installProcessHandlers: false` to
+opt out) covering two cases with no wiring needed:
+
+- **`uncaughtExceptionMonitor`**, not `uncaughtException` -- deliberately. Registering any listener
+  for `uncaughtException` *suppresses Node's own default crash behavior entirely* (the process
+  would no longer exit on its own; Node's docs are explicit that resuming normal operation
+  afterward isn't safe). `uncaughtExceptionMonitor` exists specifically for observability tools
+  like this one: it fires without changing what Node does afterward -- verified directly against a
+  real uncaught throw, not assumed.
+- **`unhandledRejection`** -- a rejected promise nobody awaited or attached a `.catch()` to,
+  arguably the most common way a modern async Node app silently fails.
+
+Neither catches a web request's unhandled exception under Express/Fastify -- both catch that
+themselves, long before it would ever reach here.
+
+Every failure mode -- network errors, timeouts, a full queue, a malformed DSN -- is caught and
+dropped rather than thrown, so a broken or unreachable tracker can never take down the host app.
+
+## Delivery: an async loop, not a thread
+
+`DeliveryQueue` here isn't a background *thread* the way the Ruby/.NET/Python clients' equivalent
+class is -- Node is single-threaded. But (unlike PHP-FPM) a Node process is long-running across many
+requests, so an async processing loop on the event loop is the natural substitute: `push()` returns
+immediately, and delivery happens via non-blocking `fetch()` calls without ever blocking the
+request that pushed it. The loop starts lazily, on first push, not at import time -- Node's
+`cluster` module can fork worker processes *after* the application has already loaded, the same
+hazard Puma/Gunicorn have for the Ruby/Python clients; starting fresh on first push means each
+forked worker gets its own live loop regardless of when it was forked relative to import.
+
+## `in_app` backtrace frames
+
+Like the Ruby gem (and unlike the .NET SDK, where a compiled assembly's file path never matches its
+original source location), Node runs interpreted directly from real `.js` files on disk, so
+file-path matching against `Configuration#appRoot` works the same way it does in the Ruby gem's
+`Rails.root` comparison. Defaults to the current working directory; set it explicitly if that
+doesn't match your app's actual layout. `node_modules` frames are never marked `in_app`, regardless
+of `appRoot`; Node's own internal modules (the `node:` scheme) never match a real `appRoot` prefix
+either, so they don't need special-casing.
+
+Backtrace parsing is a regex over `Error#stack` (a plain string in V8, unlike Python's structured
+`traceback` module or PHP's `Throwable::getTrace()`) -- verified directly against real captured
+stack traces, both synchronous and `async`, named and anonymous frames, before relying on it. A
+related quirk, shared with PHP but not Ruby/.NET/Python: V8 captures an Error's stack at
+*construction* time, not at `throw` time, so there's no "empty backtrace" case for an exception
+that's constructed but never thrown.
+
+## PII scrubbing
+
+Same behavior as the Ruby gem: the message, backtrace, and any context/tags you attach are scanned
+for likely personal data -- email addresses, formatted SSNs/credit cards, known API key/token
+formats, and anything under a suspiciously-named key (`password`, `apiKey`, `ssn`, and similar) --
+and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival
+regardless, so this is a second, earlier layer, not the only one.
+
+To disable it:
+
+```js
+forgeOpsTracker.init({ dsn: "...", scrubPii: false });
+```
+
+## Running the tests
+
+```bash
+cd sdks/node
+npm install
+npm test
+npm run lint
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@forge-ops/tracker",
+  "version": "0.1.0",
+  "description": "ForgeOps error tracking client: captures unhandled exceptions (Express/Fastify integration, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./integrations/express": "./src/integrations/express.js",
+    "./integrations/fastify": "./src/integrations/fastify.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "ForgeOps",
+  "homepage": "https://getforgeops.net",
+  "files": [
+    "src",
+    "LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint src test"
+  },
+  "peerDependencies": {
+    "express": ">=5",
+    "fastify": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "express": { "optional": true },
+    "fastify": { "optional": true }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "eslint": "^10.0.0",
+    "express": "^5.0.0",
+    "fastify": "^5.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,50 @@
+/**
+ * Delivers one payload over HTTP. Every failure mode -- DNS, connection,
+ * timeout, TLS, a non-2xx response -- is caught here and turned into a
+ * `false` return rather than a thrown exception, since a broken or
+ * unreachable tracker must never be able to break the host app. Ported
+ * from gems/forge_ops_tracker/lib/forge_ops_tracker/client.rb.
+ *
+ * Uses the global fetch() (stable since Node 18), not a package
+ * dependency (axios, node-fetch, etc.) -- same reason the Ruby gem uses
+ * plain Net::HTTP and the Python/PHP clients use only their own
+ * standard library: this has to work in any host app without adding an
+ * HTTP client dependency of its own.
+ */
+export class Client {
+  #configuration;
+
+  constructor(configuration) {
+    this.#configuration = configuration;
+  }
+
+  /** @param {Record<string, unknown>} payload */
+  async deliver(payload) {
+    const uri = this.#configuration.ingestionUri();
+    if (!uri) {
+      return false;
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.#configuration.timeoutMs);
+
+    try {
+      const response = await fetch(uri, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.#configuration.apiKey()}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      return response.ok;
+    } catch (e) {
+      this.#configuration.log(`[forge-ops-tracker] delivery failed: ${e.name}: ${e.message}`);
+      return false;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}

package/src/configuration.js

@@ -0,0 +1,94 @@
+import os from "node:os";
+
+/**
+ * Holds a single ForgeOps DSN plus everything else the client needs to
+ * build and deliver events. Mirrors gems/forge_ops_tracker's Configuration
+ * -- a single Sentry-style DSN string carries both the ingestion URL and
+ * the project's api_key: "https://<api_key>@host/api/v1/events".
+ */
+export class Configuration {
+  dsn = process.env.FORGE_OPS_DSN ?? null;
+  environment = process.env.FORGE_OPS_ENVIRONMENT ?? process.env.NODE_ENV ?? "development";
+  release = process.env.FORGE_OPS_RELEASE ?? null;
+  serverName = safeHostname();
+
+  /**
+   * Used to decide whether a backtrace frame is "in_app": a frame's file
+   * path is compared against this root. Like the Ruby gem (and unlike
+   * the .NET SDK, where a compiled assembly's file path never matches
+   * its original source location), Node runs interpreted directly from
+   * real .js files on disk, so file-path matching is the correct
+   * approach here too. Defaults to the current working directory; set
+   * explicitly if that doesn't match your app's actual layout.
+   */
+  appRoot = process.cwd();
+
+  enabledEnvironments = new Set(["production", "staging"]);
+  queueSize = 1000;
+  timeoutMs = 2000;
+  scrubPii = true;
+
+  /** @type {((message: string) => void) | null} */
+  logger = null;
+
+  /** @returns {string | null} */
+  apiKey() {
+    const parsed = this.#parsedDsn();
+    if (parsed === null || parsed.username === "") {
+      return null;
+    }
+    return decodeURIComponent(parsed.username);
+  }
+
+  /**
+   * The ingestion URL with credentials stripped out (they travel as the
+   * Authorization header instead, not embedded in the request URI).
+   * @returns {string | null}
+   */
+  ingestionUri() {
+    const parsed = this.#parsedDsn();
+    if (parsed === null) {
+      return null;
+    }
+    const stripped = new URL(parsed.toString());
+    stripped.username = "";
+    stripped.password = "";
+    return stripped.toString();
+  }
+
+  /** @returns {boolean} */
+  isEnabled() {
+    return Boolean(this.dsn) && this.apiKey() !== null && this.enabledEnvironments.has(this.environment);
+  }
+
+  /** @param {string} message */
+  log(message) {
+    this.logger?.(message);
+  }
+
+  /** @returns {URL | null} */
+  #parsedDsn() {
+    if (!this.dsn) {
+      return null;
+    }
+    try {
+      // Unlike Ruby's URI.parse, Python's urlsplit, and PHP's parse_url
+      // (all lenient, never throwing on malformed input -- verified
+      // directly for each), Node's URL constructor genuinely throws a
+      // TypeError on a malformed string. Verified directly here too,
+      // not assumed -- hence this try/catch, which the other three
+      // clients don't need.
+      return new URL(this.dsn);
+    } catch {
+      return null;
+    }
+  }
+}
+
+function safeHostname() {
+  try {
+    return os.hostname();
+  } catch {
+    return null;
+  }
+}

package/src/deliveryQueue.js

@@ -0,0 +1,71 @@
+/**
+ * A small in-process bounded queue drained by an async processing loop,
+ * so delivery never blocks the caller that raised the error and never
+ * depends on the host app having any particular job backend configured.
+ * Ported from gems/forge_ops_tracker/lib/forge_ops_tracker/delivery_queue.rb.
+ *
+ * Not a real background thread the way the Ruby/.NET/Python clients'
+ * DeliveryQueue is -- Node is single-threaded, but (unlike PHP-FPM) a
+ * Node process is long-running across many requests, so async scheduling
+ * on the event loop is the natural, idiomatic substitute: push() returns
+ * immediately, and delivery happens via non-blocking I/O (fetch) on
+ * however many microtask turns it takes, without ever blocking the
+ * request that pushed it.
+ *
+ * The processing loop is started lazily, on first push, not at
+ * construction/import time -- mirroring the Ruby/Python clients rather
+ * than assuming eager start is safe. Node's `cluster` module can fork
+ * worker processes *after* the application (and this module) has
+ * already loaded, the same hazard Puma/Gunicorn have for those clients;
+ * starting fresh on first push means each forked worker gets its own
+ * live loop regardless of when it was forked relative to import.
+ */
+export class DeliveryQueue {
+  #configuration;
+  #client;
+  #queue = [];
+  #processing = false;
+
+  constructor(configuration, client) {
+    this.#configuration = configuration;
+    this.#client = client;
+  }
+
+  /** @param {Record<string, unknown>} payload */
+  push(payload) {
+    const maxSize = Math.max(1, this.#configuration.queueSize);
+    if (this.#queue.length >= maxSize) {
+      this.#configuration.log("[forge-ops-tracker] delivery queue full, dropping event");
+      return false;
+    }
+
+    this.#queue.push(payload);
+    this.#ensureProcessing();
+    return true;
+  }
+
+  #ensureProcessing() {
+    if (this.#processing) {
+      return;
+    }
+    this.#processing = true;
+    // Deliberately not awaited -- this is the background loop itself;
+    // push() must return synchronously regardless of how long delivery
+    // takes.
+    this.#processLoop();
+  }
+
+  async #processLoop() {
+    while (this.#queue.length > 0) {
+      const payload = this.#queue.shift();
+      try {
+        await this.#client.deliver(payload);
+      } catch (e) {
+        // Per-item, not wrapping the whole loop: one bad delivery must
+        // not stop every event queued after it.
+        this.#configuration.log(`[forge-ops-tracker] delivery worker error: ${e.name}: ${e.message}`);
+      }
+    }
+    this.#processing = false;
+  }
+}

package/src/eventBuilder.js

@@ -0,0 +1,123 @@
+import { fileURLToPath } from "node:url";
+import { scrub, scrubString } from "./piiScrubber.js";
+
+const MAX_FRAMES = 500;
+
+// Parses a single V8 stack trace line, e.g.
+//   "    at innerFunc (file:///app/src/foo.js:12:9)"
+//   "    at file:///app/src/foo.js:8:3"           (no named function)
+//   "    at async asyncFn (node:internal/...:5:1)" (async frame, internal module)
+// Verified directly against real captured stack traces (both sync and
+// async, named and anonymous frames, and Node's internal node: module
+// scheme) before relying on it, not assumed to match V8's format.
+const FRAME_RE = /^\s*at\s+(?:(async)\s+)?(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?$/;
+
+/**
+ * Turns a raised exception into the payload shape the ingestion API
+ * expects. Ported from
+ * gems/forge_ops_tracker/lib/forge_ops_tracker/event_builder.rb --
+ * backtrace parsing here is a regex over V8's Error#stack string, the
+ * same general approach as the Ruby gem's own regex over MRI backtrace
+ * lines (Node doesn't expose a structured frame list the way Python's
+ * traceback module or PHP's Throwable::getTrace() do).
+ */
+export class EventBuilder {
+  #configuration;
+
+  constructor(configuration) {
+    this.#configuration = configuration;
+  }
+
+  /**
+   * @param {Error} error
+   * @param {Record<string, unknown>} [context]
+   */
+  build(error, context = {}) {
+    const payload = {
+      exception_class: error?.name ?? "Error",
+      message: error?.message ?? "",
+      backtrace: this.#backtrace(error),
+      occurred_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+      environment: this.#configuration.environment,
+      release: this.#configuration.release,
+      server_name: this.#configuration.serverName,
+      context: { ...context },
+      tags: {},
+    };
+
+    return this.#configuration.scrubPii ? this.#scrub(payload) : payload;
+  }
+
+  // exception_class/occurred_at/environment/release/server_name are left
+  // alone -- structured fields this client or the host app sets
+  // deliberately, not free text an exception or its context could
+  // accidentally spill sensitive data into.
+  #scrub(payload) {
+    return {
+      ...payload,
+      message: scrubString(payload.message),
+      backtrace: payload.backtrace.map((frame) => ({
+        ...frame,
+        file: frame.file ? scrubString(frame.file) : frame.file,
+        method: frame.method ? scrubString(frame.method) : frame.method,
+      })),
+      context: scrub(payload.context),
+      tags: scrub(payload.tags),
+    };
+  }
+
+  #backtrace(error) {
+    const stack = typeof error?.stack === "string" ? error.stack : "";
+    const frames = [];
+
+    for (const line of stack.split("\n")) {
+      if (frames.length >= MAX_FRAMES) {
+        break;
+      }
+      const match = FRAME_RE.exec(line);
+      if (!match) {
+        continue; // the "Error: message" header line, or anything unparseable
+      }
+
+      const [, , fn, rawFile, lineNo, ] = match;
+      const file = normalizeFile(rawFile);
+
+      frames.push({
+        file,
+        line: Number(lineNo),
+        method: fn ?? null,
+        in_app: this.#isInApp(file),
+      });
+    }
+
+    return frames;
+  }
+
+  #isInApp(file) {
+    const root = this.#configuration.appRoot;
+    if (!file || !root) {
+      return false;
+    }
+    if (!file.startsWith(root)) {
+      return false;
+    }
+    return !file.includes("/node_modules/");
+  }
+}
+
+// V8 stack frames use file:// URLs under ESM, but plain paths under
+// CommonJS -- normalized to a plain path either way so it's comparable
+// against Configuration#appRoot (always a plain path, from process.cwd()).
+// Node's own internal modules (the "node:" scheme) are left as-is; they
+// never match a real appRoot prefix anyway, so they're correctly never
+// marked in_app without needing special-casing here.
+function normalizeFile(rawFile) {
+  if (rawFile.startsWith("file://")) {
+    try {
+      return fileURLToPath(rawFile);
+    } catch {
+      return rawFile;
+    }
+  }
+  return rawFile;
+}

package/src/index.js

@@ -0,0 +1,117 @@
+import { Client } from "./client.js";
+import { Configuration } from "./configuration.js";
+import { DeliveryQueue } from "./deliveryQueue.js";
+import { EventBuilder } from "./eventBuilder.js";
+import { Reporter } from "./reporter.js";
+
+export { Configuration };
+
+let configuration = null;
+let reporter = null;
+let processHandlersInstalled = false;
+let uncaughtExceptionListener = null;
+let unhandledRejectionListener = null;
+
+function getConfiguration() {
+  if (configuration === null) {
+    configuration = new Configuration();
+  }
+  return configuration;
+}
+
+function getReporter() {
+  if (reporter === null) {
+    const config = getConfiguration();
+    const client = new Client(config);
+    const deliveryQueue = new DeliveryQueue(config, client);
+    reporter = new Reporter(config, new EventBuilder(config), deliveryQueue);
+  }
+  return reporter;
+}
+
+/**
+ * Configure the client. Call once at startup.
+ *
+ * @param {Partial<Configuration> & { installProcessHandlers?: boolean }} [options]
+ * @returns {Configuration}
+ */
+export function init(options = {}) {
+  const config = getConfiguration();
+  const { installProcessHandlers, ...overrides } = options;
+
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!(key in config)) {
+      throw new TypeError(`Configuration has no property ${JSON.stringify(key)}`);
+    }
+    config[key] = value;
+  }
+
+  if (installProcessHandlers ?? true) {
+    installProcessLevelHandlers();
+  }
+
+  return config;
+}
+
+/**
+ * Report an exception you've already caught.
+ *
+ * @param {Error} error
+ * @param {Record<string, unknown>} [context]
+ */
+export function captureException(error, context = {}) {
+  getReporter().report(error, context);
+}
+
+/**
+ * Reports anything that would otherwise crash the process outright (a
+ * plain script, an unhandled promise rejection) with no further wiring --
+ * the same "unhandled needs no wiring" case the Express/Fastify
+ * integrations cover for web requests.
+ *
+ * Deliberately listens on "uncaughtExceptionMonitor", not
+ * "uncaughtException" -- registering any listener for the latter
+ * *suppresses Node's own default crash behavior entirely* (the process
+ * would no longer exit on its own; official Node docs are explicit that
+ * resuming normal operation after an uncaught exception isn't safe).
+ * "uncaughtExceptionMonitor" exists specifically for observability tools
+ * like this one: it fires without changing what Node does afterward,
+ * confirmed directly (not assumed) against a real uncaught throw --
+ * Node still printed its usual crash output and exited with code 1.
+ *
+ * This does *not* catch a web request's unhandled exception under
+ * Express/Fastify -- both catch that themselves, long before it would
+ * ever reach here, which is what those integrations are for.
+ */
+function installProcessLevelHandlers() {
+  if (processHandlersInstalled) {
+    return;
+  }
+  processHandlersInstalled = true;
+
+  uncaughtExceptionListener = (error) => {
+    captureException(error);
+  };
+  unhandledRejectionListener = (reason) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    captureException(error);
+  };
+
+  process.on("uncaughtExceptionMonitor", uncaughtExceptionListener);
+  process.on("unhandledRejection", unhandledRejectionListener);
+}
+
+/** @internal not part of the public API -- resets module state between test cases */
+export function _resetForTesting() {
+  if (uncaughtExceptionListener) {
+    process.off("uncaughtExceptionMonitor", uncaughtExceptionListener);
+  }
+  if (unhandledRejectionListener) {
+    process.off("unhandledRejection", unhandledRejectionListener);
+  }
+  configuration = null;
+  reporter = null;
+  processHandlersInstalled = false;
+  uncaughtExceptionListener = null;
+  unhandledRejectionListener = null;
+}

package/src/integrations/express.js

@@ -0,0 +1,22 @@
+import { captureException } from "../index.js";
+
+/**
+ * Express error-handling middleware. Register last, after all routes:
+ *
+ *   app.use(forgeOpsTrackerExpressMiddleware);
+ *
+ * Reports, then calls next(err) so Express's own error handling (a
+ * custom error handler registered after this one, or its default 500
+ * response) continues exactly as if this middleware weren't there.
+ * Express 5 forwards both synchronous throws and rejected promises from
+ * async route handlers to error-handling middleware automatically --
+ * verified directly against a real async handler, not assumed. Only an
+ * exception your own code catches and handles is invisible to this.
+ */
+export function forgeOpsTrackerExpressMiddleware(err, req, res, next) {
+  captureException(err, {
+    path: req.path,
+    method: req.method,
+  });
+  next(err);
+}

package/src/integrations/fastify.js

@@ -0,0 +1,27 @@
+import { captureException } from "../index.js";
+
+/**
+ * Called directly with your Fastify instance -- not registered via
+ * app.register(), which would create a new encapsulation scope and
+ * require the fastify-plugin package to break out of it:
+ *
+ *   registerForgeOpsTracker(app);
+ *
+ * Adds an onError hook, which fires for any error Fastify's own
+ * lifecycle would otherwise handle -- both synchronous throws and
+ * rejected promises in async handlers, verified directly against a real
+ * async handler, not assumed. Doesn't set the reply itself, so Fastify's
+ * own error handling (setErrorHandler, or its default response)
+ * continues exactly as if this hook weren't registered. Only an
+ * exception your own code catches and handles is invisible to this.
+ *
+ * @param {import("fastify").FastifyInstance} fastify
+ */
+export function registerForgeOpsTracker(fastify) {
+  fastify.addHook("onError", async (request, reply, error) => {
+    captureException(error, {
+      path: request.url,
+      method: request.method,
+    });
+  });
+}

package/src/piiScrubber.js

@@ -0,0 +1,95 @@
+/**
+ * Redacts likely-sensitive content out of a payload before it ever leaves
+ * this process -- the same patterns ForgeOps itself applies again on
+ * arrival (defense in depth: this layer keeps the data off the wire and
+ * out of any request logging in between; the server-side layer is what
+ * actually protects the database, and doesn't depend on every reporting
+ * app running an up-to-date version of this client). Ported from
+ * gems/forge_ops_tracker/lib/forge_ops_tracker/pii_scrubber.rb -- kept
+ * standalone and dependency-free here for the same reason as the Ruby
+ * original: this has to work in any host app regardless of what's
+ * reporting into it.
+ *
+ * Can be turned off via Configuration#scrubPii = false for a host app
+ * that already scrubs its own data before it ever reaches exception
+ * context, or that has its own reasons to want the raw payload. Off by
+ * default is not an option: the safe default has to be "on."
+ */
+
+export const REDACTED = "[FILTERED]";
+
+const SENSITIVE_KEYS = new Set([
+  "password", "passwd", "pwd",
+  "secret", "apisecret", "clientsecret", "secretkey",
+  "token", "accesstoken", "refreshtoken", "apikey", "apitoken", "authorization", "authtoken", "bearer",
+  "sessiontoken", "csrftoken",
+  "creditcard", "cardnumber", "cardnum", "cvv", "cvv2", "cvc",
+  "ssn", "socialsecuritynumber", "socialsecurity",
+  "privatekey",
+]);
+
+const PATTERNS = [
+  ["EMAIL", /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g],
+  ["SSN", /\b\d{3}-\d{2}-\d{4}\b/g],
+  ["CREDIT CARD", /\b\d{4}[ -]\d{4}[ -]\d{4}[ -]\d{1,4}\b/g],
+  ["BEARER TOKEN", /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/gi],
+  ["JWT", /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g],
+  ["AWS KEY", /\bAKIA[0-9A-Z]{16}\b/g],
+  ["STRIPE KEY", /\b[sr]k_(?:live|test)_[A-Za-z0-9]{10,}\b/g],
+  ["GITHUB TOKEN", /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g],
+];
+
+/**
+ * @param {unknown} value
+ * @param {string | null} [key]
+ * @returns {unknown}
+ */
+export function scrub(value, key = null) {
+  if (isSensitiveKey(key) && value !== null && value !== undefined) {
+    return REDACTED;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((v) => scrub(v, key));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const scrubbed = {};
+    for (const [k, v] of Object.entries(value)) {
+      scrubbed[k] = scrub(v, k);
+    }
+    return scrubbed;
+  }
+
+  if (typeof value === "string") {
+    return scrubString(value);
+  }
+
+  return value;
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+export function scrubString(text) {
+  let result = text;
+  for (const [label, pattern] of PATTERNS) {
+    result = result.replace(pattern, `[${label} FILTERED]`);
+  }
+  return result;
+}
+
+/** @param {string | null} key */
+function isSensitiveKey(key) {
+  if (!key) {
+    return false;
+  }
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  for (const sensitive of SENSITIVE_KEYS) {
+    if (normalized.includes(sensitive)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/reporter.js

@@ -0,0 +1,36 @@
+/**
+ * Ties Configuration, EventBuilder, and DeliveryQueue together into the
+ * one thing callers actually need: report an exception. Mirrors
+ * gems/forge_ops_tracker's ErrorSubscriber#report -- never throws. An
+ * error reporter that itself throws while reporting an error is the
+ * worst possible failure mode, so every path here is wrapped to
+ * guarantee this never propagates back into the host app.
+ */
+export class Reporter {
+  #configuration;
+  #eventBuilder;
+  #deliveryQueue;
+
+  constructor(configuration, eventBuilder, deliveryQueue) {
+    this.#configuration = configuration;
+    this.#eventBuilder = eventBuilder;
+    this.#deliveryQueue = deliveryQueue;
+  }
+
+  /**
+   * @param {Error} error
+   * @param {Record<string, unknown>} [context]
+   */
+  report(error, context = {}) {
+    try {
+      if (!this.#configuration.isEnabled()) {
+        return;
+      }
+
+      const payload = this.#eventBuilder.build(error, context);
+      this.#deliveryQueue.push(payload);
+    } catch (e) {
+      this.#configuration.log(`[forge-ops-tracker] report failed: ${e.name}: ${e.message}`);
+    }
+  }
+}