@forge-ops/tracker 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
 # @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.
+Node.js error reporting client for a [ForgeOps](../../) instance.
+Requires Node 18+ (for global `fetch`). It captures uncaught exceptions, unhandled promise
+rejections, and explicitly reported errors, builds a backtrace, scrubs likely PII, and delivers
+events to ForgeOps over HTTP without blocking the request or process that raised them.
 
 ## Installation
 
-Not yet published to npm -- install directly from this path (or a local checkout, once split into
+Not yet published to npm: install directly from this path (or a local checkout, once split into
 its own repo):
 
 ```bash
@@ -35,12 +35,15 @@ overridden by passing it in the options object.
 ### Express
 
 ```js
+import { forgeOpsTrackerSessionTrackingExpressMiddleware } from "@forge-ops/tracker/integrations/session-tracking";
 import { forgeOpsTrackerExpressMiddleware } from "@forge-ops/tracker/integrations/express";
 
-app.use(forgeOpsTrackerExpressMiddleware); // last, after all routes
+app.use(forgeOpsTrackerSessionTrackingExpressMiddleware); // first, before any routes
+// ...routes...
+app.use(forgeOpsTrackerExpressMiddleware); // still last, after all routes
 ```
 
-Requires Express 5+ -- its automatic forwarding of both synchronous throws *and* rejected promises
+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.
@@ -54,7 +57,7 @@ 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
+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
@@ -63,7 +66,7 @@ avoids that entirely.
 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
+**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
@@ -71,13 +74,13 @@ try {
   await chargeCard(order);
 } catch (err) {
   logger.warn(`card declined: ${err.message}`);
-  // ForgeOps never sees this -- caught locally, never reaches the
+  // 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:
+There's no application-wide hook that reports an exception while still letting your own catch
+block handle it: report it explicitly instead, right at the catch site:
 
 ```js
 } catch (err) {
@@ -91,54 +94,52 @@ explicitly instead, right at the catch site:
 `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
+- **`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
+  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,
+- **`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
+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
+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.
+`DeliveryQueue` here isn't a background *thread*: Node is single-threaded. But 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, and an eagerly-started loop would be left dead in every forked child; 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.
+Node runs interpreted directly from real `.js` files on disk, so file-path matching against
+`Configuration#appRoot` is a straightforward prefix comparison against those on-disk paths.
+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 rather than a structured
+object: verified directly against real captured stack traces, both synchronous and `async`,
+named and anonymous frames, before relying on it. One quirk worth knowing: 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) --
+By default, 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.
 
@@ -148,6 +149,54 @@ To disable it:
 forgeOpsTracker.init({ dsn: "...", scrubPii: false });
 ```
 
+## Source context
+
+By default, each in-app backtrace frame (never a `node_modules` dependency) is captured along with
+the 5 lines of source on either side of the culprit line, read straight off disk at raise-time, so
+an issue's detail page can show the actual code that broke, not just a `file:line:method`
+reference. This never applies to a frame outside your configured `appRoot`, and it fails silently
+(no context, not a thrown error) for any file that can't be read for whatever reason.
+
+This is a real, deliberate exception to "off by default is safer": literal source code is being
+transmitted, not just a reference to it, and the real protection here is not this flag. Every
+project on ForgeOps has its own setting (on by default, off durably and immediately once an org
+owner turns it off, regardless of what any individual app's own `captureSourceContext` is still set
+to) that governs whether the server will ever actually store what a client sends. Set this to
+`false` if you'd rather this client never even attempt the disk read in the first place:
+
+```js
+forgeOpsTracker.init({ dsn: "...", captureSourceContext: false });
+```
+
+## Session tracking (release health)
+
+By default, every request through the Express integration is counted as a session: crash-free
+unless an unhandled exception (or a 5xx response) actually affects it, giving ForgeOps a crash-free
+rate per release to show alongside the errors themselves, not just the errors on their own.
+Counted in-process and flushed as a small periodic aggregate on a `setInterval` timer (never one
+network call per request), the same delivery philosophy as everything else in this client: a broken
+or unreachable tracker never affects the host app either way.
+
+```js
+forgeOpsTracker.init({
+  dsn: "...",
+  trackSessions: false, // opt out entirely
+  sessionFlushIntervalMs: 30000, // default 60000
+});
+```
+
+Requires a ForgeOps plan that includes release health; on a plan that doesn't, the periodic
+flushes are simply rejected server-side and dropped, exactly like any other delivery failure.
+
+One deliberate gap: unlike the Ruby gem's `at_exit`, this client does **not** hook `SIGTERM`/
+`SIGINT` to force a final flush on shutdown. Registering a listener for either signal overrides
+Node's own default disposition (the process no longer exits on its own unless something calls
+`process.exit()`), which risks racing (or outright cutting off) a host app's own graceful
+shutdown if this tracker's own listener won that race. The accepted trade-off: up to one
+`sessionFlushIntervalMs` window of session data can be lost on a hard process exit, the same way it
+would be if the interval simply hadn't ticked yet: never a behavior change for whatever app this
+is installed into. See `src/sessionFlusher.js`'s own comment for the full reasoning.
+
 ## Running the tests
 
 ```bash

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@forge-ops/tracker",
-  "version": "0.1.0",
+  "version": "0.2.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"
+    "./integrations/fastify": "./src/integrations/fastify.js",
+    "./integrations/session-tracking": "./src/integrations/sessionTracking.js"
   },
   "engines": {
     "node": ">=18"
@@ -31,8 +32,12 @@
     "fastify": ">=4"
   },
   "peerDependenciesMeta": {
-    "express": { "optional": true },
-    "fastify": { "optional": true }
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.0",

package/src/client.js

@@ -1,12 +1,12 @@
 /**
- * Delivers one payload over HTTP. Every failure mode -- DNS, connection,
- * timeout, TLS, a non-2xx response -- is caught here and turned into a
+ * 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
+ * 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.
@@ -20,7 +20,19 @@ export class Client {
 
   /** @param {Record<string, unknown>} payload */
   async deliver(payload) {
-    const uri = this.#configuration.ingestionUri();
+    return this.#post(this.#configuration.ingestionUri(), payload);
+  }
+
+  /** @param {Record<string, unknown>} payload */
+  async deliverSessionCheckin(payload) {
+    return this.#post(this.#configuration.sessionCheckinsUri(), payload);
+  }
+
+  /**
+   * @param {string | null} uri
+   * @param {Record<string, unknown>} payload
+   */
+  async #post(uri, payload) {
     if (!uri) {
       return false;
     }

package/src/configuration.js

@@ -2,8 +2,8 @@ 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
+ * build and deliver events. Mirrors gems/forge_ops_tracker's Configuration:
+ * a single DSN string carries both the ingestion URL and
  * the project's api_key: "https://<api_key>@host/api/v1/events".
  */
 export class Configuration {
@@ -28,9 +28,34 @@ export class Configuration {
   timeoutMs = 2000;
   scrubPii = true;
 
+  /**
+   * Whether EventBuilder reads a few lines of source off disk around each
+   * in-app frame's culprit line (see EventBuilder#attachSourceContext).
+   * Defaults to true so a snippet shows up with no extra setup, but this
+   * flag by itself isn't what actually keeps proprietary source code from
+   * ending up somewhere it shouldn't: ForgeOps' own per-project setting is
+   * the durable, server-enforced off switch, since it applies no matter
+   * what this flag happens to be set to on any given deployment, and can't
+   * quietly drift back on the way a local config value could. Set this to
+   * false too if this host app should never even attempt that disk read in
+   * the first place.
+   */
+  captureSourceContext = true;
+
   /** @type {((message: string) => void) | null} */
   logger = null;
 
+  /**
+   * Whether the Express/Fastify integrations count every request as a session (crash-free
+   * unless an unhandled exception actually escaped it) and periodically report an aggregate
+   * crash-free rate. On by default, the same "on unless you turn it off" posture error
+   * tracking itself already has.
+   */
+  trackSessions = true;
+  /** Milliseconds between aggregate session reports; requests are counted in-process and
+   * flushed as one small report on this interval, not one network call per request. */
+  sessionFlushIntervalMs = 60000;
+
   /** @returns {string | null} */
   apiKey() {
     const parsed = this.#parsedDsn();
@@ -56,6 +81,19 @@ export class Configuration {
     return stripped.toString();
   }
 
+  /**
+   * Same derivation as ingestionUri, with the trailing /events swapped for /session_checkins:
+   * one DSN, two endpoints, matching the Ruby gem's own Configuration#session_checkins_uri.
+   * @returns {string | null}
+   */
+  sessionCheckinsUri() {
+    const uri = this.ingestionUri();
+    if (!uri) {
+      return null;
+    }
+    return uri.replace(/\/events$/, "/session_checkins");
+  }
+
   /** @returns {boolean} */
   isEnabled() {
     return Boolean(this.dsn) && this.apiKey() !== null && this.enabledEnvironments.has(this.environment);
@@ -73,10 +111,10 @@ export class Configuration {
     }
     try {
       // Unlike Ruby's URI.parse, Python's urlsplit, and PHP's parse_url
-      // (all lenient, never throwing on malformed input -- verified
+      // (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
+      // not assumed: hence this try/catch, which the other three
       // clients don't need.
       return new URL(this.dsn);
     } catch {

package/src/deliveryQueue.js

@@ -5,7 +5,7 @@
  * 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
+ * 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
@@ -13,7 +13,7 @@
  * request that pushed it.
  *
  * The processing loop is started lazily, on first push, not at
- * construction/import time -- mirroring the Ruby/Python clients rather
+ * 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;
@@ -49,7 +49,7 @@ export class DeliveryQueue {
       return;
     }
     this.#processing = true;
-    // Deliberately not awaited -- this is the background loop itself;
+    // Deliberately not awaited: this is the background loop itself;
     // push() must return synchronously regardless of how long delivery
     // takes.
     this.#processLoop();

package/src/eventBuilder.js

@@ -1,8 +1,23 @@
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { scrub, scrubString } from "./piiScrubber.js";
 
 const MAX_FRAMES = 500;
 
+// How many lines of source to grab on either side of the culprit line (see
+// #attachSourceContext), and the longest a single captured line is allowed
+// to be before getting truncated: guards against one pathological
+// minified/generated line ballooning the payload. ForgeOps itself
+// re-truncates on arrival too, the same "don't just trust the SDK" posture
+// MAX_FRAMES already gets on the server side.
+const CONTEXT_LINES = 5;
+const MAX_CONTEXT_LINE_LENGTH = 500;
+
+// Identifies this client to the server's auto language-detection on the project the event lands
+// in (see Project#note_sdk_platform server-side); matches this repo's own sdks/node directory
+// name, the same convention every other language's client follows.
+const SDK_NAME = "node";
+
 // 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)
@@ -15,7 +30,7 @@ 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 --
+ * 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
@@ -43,29 +58,40 @@ export class EventBuilder {
       server_name: this.#configuration.serverName,
       context: { ...context },
       tags: {},
+      sdk_name: SDK_NAME,
     };
 
     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
+  // 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,
-      })),
+      backtrace: payload.backtrace.map((frame) => this.#scrubFrame(frame)),
       context: scrub(payload.context),
       tags: scrub(payload.tags),
     };
   }
 
+  #scrubFrame(frame) {
+    const scrubbed = {
+      ...frame,
+      file: frame.file ? scrubString(frame.file) : frame.file,
+      method: frame.method ? scrubString(frame.method) : frame.method,
+    };
+    if ("context_line" in scrubbed) {
+      scrubbed.context_line = scrubString(scrubbed.context_line);
+      scrubbed.pre_context = scrubbed.pre_context.map(scrubString);
+      scrubbed.post_context = scrubbed.post_context.map(scrubString);
+    }
+    return scrubbed;
+  }
+
   #backtrace(error) {
     const stack = typeof error?.stack === "string" ? error.stack : "";
     const frames = [];
@@ -82,12 +108,14 @@ export class EventBuilder {
       const [, , fn, rawFile, lineNo, ] = match;
       const file = normalizeFile(rawFile);
 
-      frames.push({
-        file,
-        line: Number(lineNo),
-        method: fn ?? null,
-        in_app: this.#isInApp(file),
-      });
+      frames.push(
+        this.#attachSourceContext({
+          file,
+          line: Number(lineNo),
+          method: fn ?? null,
+          in_app: this.#isInApp(file),
+        }),
+      );
     }
 
     return frames;
@@ -103,10 +131,69 @@ export class EventBuilder {
     }
     return !file.includes("/node_modules/");
   }
+
+  // Reads a few lines of source straight off disk around the culprit line,
+  // at raise-time, in the same running process the exception came from.
+  // Gated on two things: the frame has to be in-app (never a
+  // node_modules/vendored dependency: there'd be nothing meaningful to
+  // show, and it's not the host app's own code to begin with), and
+  // configuration.captureSourceContext has to be true (see Configuration
+  // for why it defaults to true and why ForgeOps' own per-project setting,
+  // not this flag, is the durable, protected way to turn it off).
+  // Best-effort: any file that can't be read (deleted, permission denied, a
+  // path that only ever existed inside a build step and isn't present in
+  // this deployment) just means this one frame gets no source context,
+  // never a thrown error of its own.
+  #attachSourceContext(frame) {
+    if (!this.#configuration.captureSourceContext || !frame.in_app) {
+      return frame;
+    }
+
+    let lines;
+    try {
+      lines = splitLines(fs.readFileSync(frame.file, "utf8"));
+    } catch {
+      return frame;
+    }
+
+    const index = frame.line - 1;
+    if (index < 0 || index >= lines.length) {
+      return frame;
+    }
+
+    const from = Math.max(index - CONTEXT_LINES, 0);
+    const to = Math.min(index + CONTEXT_LINES, lines.length - 1);
+
+    return {
+      ...frame,
+      context_line: truncateLine(lines[index]),
+      pre_context: lines.slice(from, index).map(truncateLine),
+      post_context: lines.slice(index + 1, to + 1).map(truncateLine),
+    };
+  }
+}
+
+// Splits file content into lines the same way Ruby's File.readlines and
+// Python's readlines() do: no phantom empty final element when the file
+// ends with a trailing newline (a plain `content.split("\n")` would add
+// one), and no trailing "\r" left over from a CRLF line ending.
+function splitLines(content) {
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) {
+    lines.pop();
+  }
+  return lines.map((line) => line.replace(/\r$/, ""));
+}
+
+function truncateLine(line) {
+  if (line.length <= MAX_CONTEXT_LINE_LENGTH) {
+    return line;
+  }
+  return `${line.slice(0, MAX_CONTEXT_LINE_LENGTH)}...`;
 }
 
 // V8 stack frames use file:// URLs under ESM, but plain paths under
-// CommonJS -- normalized to a plain path either way so it's comparable
+// 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

package/src/index.js

@@ -3,11 +3,13 @@ import { Configuration } from "./configuration.js";
 import { DeliveryQueue } from "./deliveryQueue.js";
 import { EventBuilder } from "./eventBuilder.js";
 import { Reporter } from "./reporter.js";
+import { SessionFlusher } from "./sessionFlusher.js";
 
 export { Configuration };
 
 let configuration = null;
 let reporter = null;
+let sessionFlusher = null;
 let processHandlersInstalled = false;
 let uncaughtExceptionListener = null;
 let unhandledRejectionListener = null;
@@ -29,6 +31,29 @@ function getReporter() {
   return reporter;
 }
 
+function getSessionFlusher() {
+  if (sessionFlusher === null) {
+    const config = getConfiguration();
+    sessionFlusher = new SessionFlusher(config, new Client(config));
+  }
+  return sessionFlusher;
+}
+
+/**
+ * Internal; called by the Express/Fastify session-tracking integrations, never by host app
+ * code directly (there's nothing for a caller to decide here beyond what the middleware/hook
+ * itself already observed).
+ *
+ * @param {boolean} crashed
+ */
+export function _recordSession(crashed) {
+  const config = getConfiguration();
+  if (!config.trackSessions || !config.isEnabled()) {
+    return;
+  }
+  getSessionFlusher().recordSession(crashed);
+}
+
 /**
  * Configure the client. Call once at startup.
  *
@@ -65,22 +90,22 @@ export function captureException(error, context = {}) {
 
 /**
  * Reports anything that would otherwise crash the process outright (a
- * plain script, an unhandled promise rejection) with no further wiring --
+ * 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
+ * "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 --
+ * 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
+ * Express/Fastify: both catch that themselves, long before it would
  * ever reach here, which is what those integrations are for.
  */
 function installProcessLevelHandlers() {
@@ -101,7 +126,7 @@ function installProcessLevelHandlers() {
   process.on("unhandledRejection", unhandledRejectionListener);
 }
 
-/** @internal not part of the public API -- resets module state between test cases */
+/** @internal not part of the public API: resets module state between test cases */
 export function _resetForTesting() {
   if (uncaughtExceptionListener) {
     process.off("uncaughtExceptionMonitor", uncaughtExceptionListener);
@@ -111,6 +136,7 @@ export function _resetForTesting() {
   }
   configuration = null;
   reporter = null;
+  sessionFlusher = null;
   processHandlersInstalled = false;
   uncaughtExceptionListener = null;
   unhandledRejectionListener = null;

package/src/integrations/express.js

@@ -9,11 +9,17 @@ import { captureException } from "../index.js";
  * 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 --
+ * 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) {
+  // See integrations/sessionTracking.js's own comment: marks the request crashed before
+  // anything else, so its res.on("finish") listener (which fires later, once this or
+  // whatever error handling runs after it actually sends a response) already sees this by
+  // the time it checks.
+  req._forgeOpsSessionCrashed = true;
+
   captureException(err, {
     path: req.path,
     method: req.method,

package/src/integrations/fastify.js

@@ -1,14 +1,14 @@
 import { captureException } from "../index.js";
 
 /**
- * Called directly with your Fastify instance -- not registered via
+ * 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
+ * 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)

package/src/integrations/sessionTracking.js

@@ -0,0 +1,32 @@
+import { _recordSession } from "../index.js";
+
+/**
+ * Express session-tracking middleware. Register FIRST, before any routes:
+ *
+ *   app.use(forgeOpsTrackerSessionTrackingExpressMiddleware);
+ *   // ...routes...
+ *   app.use(forgeOpsTrackerExpressMiddleware); // still last, per its own doc comment
+ *
+ * Counts every request as a session (crash-free unless an unhandled exception actually
+ * affected it) toward the crash-free rate on a project's Releases page. A separate,
+ * independent middleware from forgeOpsTrackerExpressMiddleware, not layered onto it, since
+ * session tracking runs regardless of whether error reporting is even configured, mirroring
+ * gems/forge_ops_tracker's own split between its Rack middleware (sessions) and its
+ * Rails.error hook (errors), two genuinely independent mechanisms.
+ *
+ * Express has no single call that wraps a whole request/response cycle the way Rack's
+ * app.call(env) does, so "crashed" is read from two signals rather than one: the response's
+ * own final status code (>= 500, Express's own default for an unhandled error even with no
+ * error-handling middleware installed at all), and a request-scoped flag that
+ * forgeOpsTrackerExpressMiddleware sets before it does anything else, for the case a host app
+ * has its own custom error handler that responds with something other than a plain 500. Either
+ * signal alone would work when both middlewares are installed; checking both means session
+ * tracking still works correctly even when the error-reporting middleware isn't.
+ */
+export function forgeOpsTrackerSessionTrackingExpressMiddleware(req, res, next) {
+  req._forgeOpsSessionCrashed = false;
+  res.on("finish", () => {
+    _recordSession(req._forgeOpsSessionCrashed || res.statusCode >= 500);
+  });
+  next();
+}

package/src/piiScrubber.js

@@ -1,11 +1,11 @@
 /**
  * Redacts likely-sensitive content out of a payload before it ever leaves
- * this process -- the same patterns ForgeOps itself applies again on
+ * 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
+ * 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.

package/src/reporter.js

@@ -1,7 +1,7 @@
 /**
  * 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
+ * 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.

package/src/sessionFlusher.js

@@ -0,0 +1,91 @@
+/**
+ * Counts requests and crashes in-process (see the Express/Fastify session-tracking
+ * integrations) and periodically flushes the totals as one small aggregate report, rather
+ * than one network call per request. Ported from
+ * gems/forge_ops_tracker/lib/forge_ops_tracker/session_flusher.rb.
+ *
+ * setInterval(...).unref(), not a real background thread; Node is single-threaded, and
+ * unref() specifically so an idle flush timer never holds a short script's process open on
+ * its own, the same "never affect the host app just by being configured" principle
+ * DeliveryQueue's own lazy start already follows.
+ *
+ * Deliberately does NOT hook SIGTERM/SIGINT to force a final flush the way Ruby's at_exit
+ * does. Considered and rejected: registering a listener for either signal overrides Node's
+ * own default disposition (the process no longer exits on its own; something has to call
+ * process.exit() explicitly), which risks racing with, or outright cutting off, a host app's
+ * own graceful shutdown (draining in-flight requests, closing a database pool) if this
+ * tracker's own listener calls exit() first. That's a real correctness risk to the host app
+ * itself, not just a data-completeness one, and this SDK's whole design already treats "never
+ * affect the host app" as non-negotiable everywhere else (Client#deliver never throws,
+ * DeliveryQueue drops rather than blocks when full). The accepted trade-off instead: up to one
+ * sessionFlushIntervalMs window of session data can be lost on a hard process exit, the same
+ * way it would be if the interval simply hadn't ticked yet: a bounded, honest gap, not a
+ * behavior change for whatever app this is installed into.
+ */
+export class SessionFlusher {
+  #configuration;
+  #client;
+  #sessionsCount = 0;
+  #crashedSessionsCount = 0;
+  #periodStartedAt = new Date();
+  #timer = null;
+
+  constructor(configuration, client) {
+    this.#configuration = configuration;
+    this.#client = client;
+  }
+
+  /** @param {boolean} crashed */
+  recordSession(crashed) {
+    this.#ensureTimerStarted();
+    this.#sessionsCount += 1;
+    if (crashed) {
+      this.#crashedSessionsCount += 1;
+    }
+  }
+
+  /**
+   * Snapshots and resets the in-process counters, then delivers them. A failed delivery keeps
+   * the counts where they are rather than resetting, so the next flush's window just grows
+   * instead of losing what was already tallied; there's no other copy of this data anywhere.
+   */
+  async flush() {
+    if (this.#sessionsCount === 0) {
+      return;
+    }
+
+    const snapshot = {
+      release: this.#configuration.release,
+      environment: this.#configuration.environment,
+      period_started_at: this.#periodStartedAt.toISOString(),
+      period_ended_at: new Date().toISOString(),
+      sessions_count: this.#sessionsCount,
+      crashed_sessions_count: this.#crashedSessionsCount,
+    };
+
+    const delivered = await this.#client.deliverSessionCheckin(snapshot);
+    if (!delivered) {
+      return;
+    }
+
+    this.#sessionsCount = 0;
+    this.#crashedSessionsCount = 0;
+    this.#periodStartedAt = new Date();
+  }
+
+  #ensureTimerStarted() {
+    if (this.#timer !== null) {
+      return;
+    }
+
+    this.#timer = setInterval(() => {
+      this.flush().catch((e) => {
+        // Per-tick, not left to reject silently: one bad flush must not kill every flush
+        // after it (setInterval keeps calling this callback regardless either way, but a
+        // silently swallowed rejection would still be worth logging).
+        this.#configuration.log(`[forge-ops-tracker] session flush error: ${e.name}: ${e.message}`);
+      });
+    }, this.#configuration.sessionFlushIntervalMs);
+    this.#timer.unref();
+  }
+}