midline-agent 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `midline-agent`, compiled from git history. Dates reflect commit dates, newest first.
+
+## 2026-09-17
+- feat: `midline-agent/browser` captures pageviews — on load and on every SPA route change — as the
+  basis for visitor counting and funnel views in the Midline dashboard (0.5.0)
+- feat: every browser event carries a top-level `sessionId`, stable for the tab's lifetime
+
+## 2026-09-14
+- chore: bump version to 0.4.1
+- chore: add socket.io dependencies and update configuration
+
+## 2026-09-13
+- feat: midline-agent/browser, a browser SDK in the same package (0.4.0)
+- docs: console lines show on the Terminal page, and 5xx responses group into Issues
+- docs: add README for midline-agent SDK
+- feat!: midline-agent 0.2.0 — verified TLS only, proxy mode, safe delivery (breaking)
+- feat: add midline-agent package with core types, configuration, and agent implementation
+
+## 2026-09-12
+- first commit
+- feat: add midline-agent package for event monitoring and reporting
+- Update agent API endpoint to api.usemidline.com
+- docs: expand README with detailed NestJS, Node.js, and Express.js setup guides

package/README.md

@@ -378,9 +378,10 @@ app.get("/x", (req, res) => { logger.info({ requestId: getRequestContext(req)?.r
 ## Browser apps
 
 `midline-agent/browser` monitors a web app from the page: uncaught errors and unhandled rejections,
-failed `fetch` and `XMLHttpRequest` calls, Web Vitals (LCP, INP, CLS, FCP, TTFB) and, if you ask,
-console output. It has no dependencies, no Node code, and works under React, Vue, Angular, Svelte,
-Next.js or no framework at all, because it instruments the page rather than a framework.
+failed `fetch` and `XMLHttpRequest` calls, Web Vitals (LCP, INP, CLS, FCP, TTFB), pageviews for
+visitor counting and funnel views, and, if you ask, console output. It has no dependencies, no Node
+code, and works under React, Vue, Angular, Svelte, Next.js or no framework at all, because it
+instruments the page rather than a framework.
 
 ```ts
 import * as Midline from "midline-agent/browser";
@@ -424,6 +425,7 @@ the browser will block the call's preflight.
 | `captureErrors` | `true` | Uncaught errors and unhandled rejections. |
 | `captureRequests` | `"failed"` | `"failed"` (4xx, 5xx, network errors), `"all"`, or `false`. Every call is a breadcrumb either way. |
 | `captureWebVitals` | `true` | Reported once, when the page is first hidden. |
+| `capturePageviews` | `true` | A `pageview` event on load and on every SPA route change (`pushState`/`replaceState`/`popstate`), tagged with a per-tab `sessionId` — what the dashboard's visitor and funnel views are built from. |
 | `captureConsole` | `false` | `true` for `error` and `warn`, or a list of levels. Lines appear on the Terminal page. Opt-in because wrapped console calls show the SDK as their source in devtools. |
 | `tracePropagationTargets` | same origin | Strings match as URL prefixes (or path prefixes starting with `/`); RegExps match the full URL. |
 | `ignoreErrors`, `ignoreUrls` | `[]` | Strings match as substrings. |
@@ -446,7 +448,7 @@ No bundler? Load the ES module build directly:
 
 ```html
 <script type="module">
-  import * as Midline from "https://cdn.jsdelivr.net/npm/midline-agent@0.4.0/dist/esm/browser/index.js";
+  import * as Midline from "https://cdn.jsdelivr.net/npm/midline-agent@0.5.0/dist/esm/browser/index.js";
   Midline.init({ apiKey: "pk_…", service: "web" });
 </script>
 ```
@@ -476,8 +478,8 @@ Authenticate with the `X-API-Key` header. An `apiKey` field in the body is still
 
 | Field | Required | Notes |
 | --- | --- | --- |
-| `eventType` | yes | `request` · `error` · `security` · `performance` · `custom` |
-| `route` | yes | Path only, e.g. `/v1/charges` |
+| `eventType` | yes | `request` · `error` · `security` · `performance` · `pageview` · `custom` |
+| `route` | yes | Path only, e.g. `/v1/charges`. For `pageview`, the page path. |
 | `method` | no | HTTP method |
 | `statusCode` | no | 100–599 |
 | `responseTime` | no | Milliseconds |
@@ -486,6 +488,7 @@ Authenticate with the `X-API-Key` header. An `apiKey` field in the body is still
 | `service` / `environment` / `release` | no | Where it came from |
 | `timestamp` | no | ISO 8601; clamped to server time if implausibly far off |
 | `requestId` / `correlationId` / `traceId` | no | For joining events across services |
+| `sessionId` | no | A stable id for one visitor's session (e.g. a browser tab). Send the same value on every event from that session and Midline can build visitor counts and funnels from `pageview` events. Keep it opaque — never an email or a real user id. |
 | `payload` | no | Free-form context — error message, stack, captured request/response |
 | `metadata` | no | Free-form, e.g. SDK name and version |
 

package/dist/browser/client.d.ts

@@ -41,6 +41,7 @@ export declare class BrowserClient {
     private handleRequest;
     private handleConsole;
     private handleNavigation;
+    private handlePageview;
     private handleVitals;
     private propagation;
     private base;

package/dist/browser/client.js

@@ -26,7 +26,7 @@ const CONSOLE_SEVERITY = {
 /** Top-level fields the ingest API accepts from this SDK; it rejects the whole batch on anything else. */
 const WIRE_FIELDS = new Set([
     "eventType", "route", "method", "statusCode", "responseTime", "severity", "category", "timestamp",
-    "service", "environment", "release", "userAgent", "traceId", "spanId", "payload", "metadata",
+    "service", "environment", "release", "userAgent", "traceId", "spanId", "sessionId", "payload", "metadata",
 ]);
 class BrowserConfigError extends Error {
 }
@@ -81,6 +81,7 @@ function resolve(config) {
         captureRequests: config.captureRequests === undefined ? "failed" : config.captureRequests,
         consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
         captureWebVitals: config.captureWebVitals !== false,
+        capturePageviews: config.capturePageviews !== false,
         tracePropagationTargets: config.tracePropagationTargets,
         ignoreErrors: config.ignoreErrors ?? [],
         ignoreUrls: config.ignoreUrls ?? [],
@@ -169,6 +170,9 @@ class BrowserClient {
         if (this.config.captureWebVitals) {
             this.teardowns.push((0, vitals_js_1.observeVitals)(this.win, (report) => this.handleVitals(report)));
         }
+        if (this.config.capturePageviews) {
+            this.handlePageview(this.currentRoute(), this.win.document?.referrer || undefined);
+        }
         // Registered after the vitals listener so its event is queued before this sends.
         const onHide = () => {
             if (this.win.document?.visibilityState === "hidden")
@@ -327,6 +331,16 @@ class BrowserClient {
         // A new view is a new trace, so its API calls don't blur into the last one's.
         this.traceId = randomHex(16);
         this.breadcrumb("navigation", `${pathOf(from)} -> ${pathOf(to)}`);
+        // history.pushState/replaceState have already run by the time this fires, so
+        // win.location — and therefore currentRoute() — reflects the new view.
+        if (this.config.capturePageviews)
+            this.handlePageview(this.currentRoute());
+    }
+    handlePageview(route, referrer) {
+        const event = this.base("pageview", route, "low", "application");
+        if (referrer)
+            event.payload = { referrer: this.redactor.string(referrer, 2048) };
+        this.emit(event);
     }
     handleVitals(report) {
         const poor = Object.values(report.vitals).some((vital) => vital?.rating === "poor");
@@ -356,7 +370,6 @@ class BrowserClient {
             sdk: "midline-agent/browser",
             version: version_js_1.BROWSER_SDK_VERSION,
             runtime: "browser",
-            sessionId: this.sessionId,
             page: { url: this.pageUrl(), path: this.currentRoute() },
         };
         if (this.user && (this.user.id || this.user.username))
@@ -375,6 +388,7 @@ class BrowserClient {
             release: this.config.release,
             userAgent: clamp(nav?.userAgent, 512),
             traceId: this.traceId,
+            sessionId: this.sessionId,
             metadata,
         };
     }

package/dist/browser/types.d.ts

@@ -36,6 +36,12 @@ export interface MidlineBrowserConfig {
     captureConsole?: boolean | ConsoleLevel[];
     /** LCP, INP, CLS, FCP and TTFB, reported once when the page is first hidden. Default true. */
     captureWebVitals?: boolean;
+    /**
+     * A `pageview` event on load and on every SPA route change (history push/replace/popstate),
+     * carrying the same per-tab `sessionId` as every other event. This is what a visitor-count or
+     * funnel view in the Midline dashboard is built from. Default true.
+     */
+    capturePageviews?: boolean;
     /**
      * Requests that get a W3C `traceparent` header, so the backend's midline-agent
      * links its request to this page. Strings match as URL prefixes (or path prefixes
@@ -71,7 +77,7 @@ export interface MidlineBrowserConfig {
 }
 /** An event as it is sent to the ingest API. */
 export interface BrowserEvent {
-    eventType: "error" | "request" | "console" | "performance" | "custom";
+    eventType: "error" | "request" | "console" | "performance" | "pageview" | "custom";
     route: string;
     method?: string;
     statusCode?: number;
@@ -85,6 +91,8 @@ export interface BrowserEvent {
     userAgent?: string;
     traceId?: string;
     spanId?: string;
+    /** Stable for the tab's lifetime (sessionStorage-backed). Same value on every event this SDK sends. */
+    sessionId?: string;
     payload?: Record<string, unknown>;
     metadata: Record<string, unknown>;
 }

package/dist/browser/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-export declare const BROWSER_SDK_VERSION = "0.4.0";
+export declare const BROWSER_SDK_VERSION = "0.5.0";

package/dist/browser/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BROWSER_SDK_VERSION = void 0;
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-exports.BROWSER_SDK_VERSION = "0.4.0";
+exports.BROWSER_SDK_VERSION = "0.5.0";

package/dist/esm/browser/client.js

@@ -21,7 +21,7 @@ const CONSOLE_SEVERITY = {
 /** Top-level fields the ingest API accepts from this SDK; it rejects the whole batch on anything else. */
 const WIRE_FIELDS = new Set([
     "eventType", "route", "method", "statusCode", "responseTime", "severity", "category", "timestamp",
-    "service", "environment", "release", "userAgent", "traceId", "spanId", "payload", "metadata",
+    "service", "environment", "release", "userAgent", "traceId", "spanId", "sessionId", "payload", "metadata",
 ]);
 export class BrowserConfigError extends Error {
 }
@@ -75,6 +75,7 @@ function resolve(config) {
         captureRequests: config.captureRequests === undefined ? "failed" : config.captureRequests,
         consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
         captureWebVitals: config.captureWebVitals !== false,
+        capturePageviews: config.capturePageviews !== false,
         tracePropagationTargets: config.tracePropagationTargets,
         ignoreErrors: config.ignoreErrors ?? [],
         ignoreUrls: config.ignoreUrls ?? [],
@@ -163,6 +164,9 @@ export class BrowserClient {
         if (this.config.captureWebVitals) {
             this.teardowns.push(observeVitals(this.win, (report) => this.handleVitals(report)));
         }
+        if (this.config.capturePageviews) {
+            this.handlePageview(this.currentRoute(), this.win.document?.referrer || undefined);
+        }
         // Registered after the vitals listener so its event is queued before this sends.
         const onHide = () => {
             if (this.win.document?.visibilityState === "hidden")
@@ -321,6 +325,16 @@ export class BrowserClient {
         // A new view is a new trace, so its API calls don't blur into the last one's.
         this.traceId = randomHex(16);
         this.breadcrumb("navigation", `${pathOf(from)} -> ${pathOf(to)}`);
+        // history.pushState/replaceState have already run by the time this fires, so
+        // win.location — and therefore currentRoute() — reflects the new view.
+        if (this.config.capturePageviews)
+            this.handlePageview(this.currentRoute());
+    }
+    handlePageview(route, referrer) {
+        const event = this.base("pageview", route, "low", "application");
+        if (referrer)
+            event.payload = { referrer: this.redactor.string(referrer, 2048) };
+        this.emit(event);
     }
     handleVitals(report) {
         const poor = Object.values(report.vitals).some((vital) => vital?.rating === "poor");
@@ -350,7 +364,6 @@ export class BrowserClient {
             sdk: "midline-agent/browser",
             version: BROWSER_SDK_VERSION,
             runtime: "browser",
-            sessionId: this.sessionId,
             page: { url: this.pageUrl(), path: this.currentRoute() },
         };
         if (this.user && (this.user.id || this.user.username))
@@ -369,6 +382,7 @@ export class BrowserClient {
             release: this.config.release,
             userAgent: clamp(nav?.userAgent, 512),
             traceId: this.traceId,
+            sessionId: this.sessionId,
             metadata,
         };
     }

package/dist/esm/browser/version.js

@@ -1,2 +1,2 @@
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-export const BROWSER_SDK_VERSION = "0.4.0";
+export const BROWSER_SDK_VERSION = "0.5.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "midline-agent",
-  "version": "0.4.1",
-  "description": "Midline — request, error and security monitoring for Node, and error, network and Web Vitals monitoring for browsers",
+  "version": "0.5.0",
+  "description": "Midline — request, error and security monitoring for Node, and error, network, Web Vitals and pageview/visitor monitoring for browsers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/src/browser/client.ts

@@ -44,7 +44,7 @@ const CONSOLE_SEVERITY: Record<ConsoleLevel, EventSeverity> = {
 /** Top-level fields the ingest API accepts from this SDK; it rejects the whole batch on anything else. */
 const WIRE_FIELDS = new Set<string>([
   "eventType", "route", "method", "statusCode", "responseTime", "severity", "category", "timestamp",
-  "service", "environment", "release", "userAgent", "traceId", "spanId", "payload", "metadata",
+  "service", "environment", "release", "userAgent", "traceId", "spanId", "sessionId", "payload", "metadata",
 ]);
 
 interface Resolved {
@@ -58,6 +58,7 @@ interface Resolved {
   captureRequests: RequestCapture;
   consoleLevels: ConsoleLevel[];
   captureWebVitals: boolean;
+  capturePageviews: boolean;
   tracePropagationTargets?: Array<string | RegExp>;
   ignoreErrors: Array<string | RegExp>;
   ignoreUrls: Array<string | RegExp>;
@@ -124,6 +125,7 @@ function resolve(config: MidlineBrowserConfig): Resolved {
     captureRequests: config.captureRequests === undefined ? "failed" : config.captureRequests,
     consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
     captureWebVitals: config.captureWebVitals !== false,
+    capturePageviews: config.capturePageviews !== false,
     tracePropagationTargets: config.tracePropagationTargets,
     ignoreErrors: config.ignoreErrors ?? [],
     ignoreUrls: config.ignoreUrls ?? [],
@@ -222,6 +224,9 @@ export class BrowserClient {
     if (this.config.captureWebVitals) {
       this.teardowns.push(observeVitals(this.win, (report) => this.handleVitals(report)));
     }
+    if (this.config.capturePageviews) {
+      this.handlePageview(this.currentRoute(), this.win.document?.referrer || undefined);
+    }
 
     // Registered after the vitals listener so its event is queued before this sends.
     const onHide = () => {
@@ -399,6 +404,15 @@ export class BrowserClient {
     // A new view is a new trace, so its API calls don't blur into the last one's.
     this.traceId = randomHex(16);
     this.breadcrumb("navigation", `${pathOf(from)} -> ${pathOf(to)}`);
+    // history.pushState/replaceState have already run by the time this fires, so
+    // win.location — and therefore currentRoute() — reflects the new view.
+    if (this.config.capturePageviews) this.handlePageview(this.currentRoute());
+  }
+
+  private handlePageview(route: string, referrer?: string): void {
+    const event = this.base("pageview", route, "low", "application");
+    if (referrer) event.payload = { referrer: this.redactor.string(referrer, 2048) };
+    this.emit(event);
   }
 
   private handleVitals(report: VitalsReport): void {
@@ -438,7 +452,6 @@ export class BrowserClient {
       sdk: "midline-agent/browser",
       version: BROWSER_SDK_VERSION,
       runtime: "browser",
-      sessionId: this.sessionId,
       page: { url: this.pageUrl(), path: this.currentRoute() },
     };
     if (this.user && (this.user.id || this.user.username)) metadata.user = { ...this.user };
@@ -456,6 +469,7 @@ export class BrowserClient {
       release: this.config.release,
       userAgent: clamp(nav?.userAgent, 512),
       traceId: this.traceId,
+      sessionId: this.sessionId,
       metadata,
     };
   }

package/src/browser/types.ts

@@ -42,6 +42,12 @@ export interface MidlineBrowserConfig {
   captureConsole?: boolean | ConsoleLevel[];
   /** LCP, INP, CLS, FCP and TTFB, reported once when the page is first hidden. Default true. */
   captureWebVitals?: boolean;
+  /**
+   * A `pageview` event on load and on every SPA route change (history push/replace/popstate),
+   * carrying the same per-tab `sessionId` as every other event. This is what a visitor-count or
+   * funnel view in the Midline dashboard is built from. Default true.
+   */
+  capturePageviews?: boolean;
 
   /**
    * Requests that get a W3C `traceparent` header, so the backend's midline-agent
@@ -81,7 +87,7 @@ export interface MidlineBrowserConfig {
 
 /** An event as it is sent to the ingest API. */
 export interface BrowserEvent {
-  eventType: "error" | "request" | "console" | "performance" | "custom";
+  eventType: "error" | "request" | "console" | "performance" | "pageview" | "custom";
   route: string;
   method?: string;
   statusCode?: number;
@@ -95,6 +101,8 @@ export interface BrowserEvent {
   userAgent?: string;
   traceId?: string;
   spanId?: string;
+  /** Stable for the tab's lifetime (sessionStorage-backed). Same value on every event this SDK sends. */
+  sessionId?: string;
   payload?: Record<string, unknown>;
   metadata: Record<string, unknown>;
 }

package/src/browser/version.ts

@@ -1,2 +1,2 @@
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-export const BROWSER_SDK_VERSION = "0.4.0";
+export const BROWSER_SDK_VERSION = "0.5.0";

package/test/browser.test.js

@@ -75,7 +75,7 @@ function uncaught(win, error, extra = {}) {
 
 async function withSdk(config, run, windowOptions) {
   const env = fakeWindow(windowOptions);
-  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, ...config });
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, capturePageviews: false, ...config });
   try {
     await run(env);
   } finally {
@@ -298,7 +298,7 @@ test("browser: navigation starts a new trace; close restores everything it wrapp
   const originalPush = win.history.pushState;
   const originalError = win.console.error;
 
-  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, captureConsole: true });
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, capturePageviews: false, captureConsole: true });
   assert.notEqual(win.fetch, originalFetch);
 
   Midline.captureMessage("before");
@@ -316,6 +316,52 @@ test("browser: navigation starts a new trace; close restores everything it wrapp
   delete globalThis.window;
 });
 
+test("browser: pageviews fire on load and on SPA navigation, sharing one sessionId", async () => {
+  const env = fakeWindow();
+  const { win } = env;
+  win.document.referrer = "https://google.com/search";
+
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false });
+  win.history.pushState({}, "", "/pricing");
+  win.history.replaceState({}, "", "/pricing/annual");
+  await Midline.flush();
+
+  const [initial, pushed, replaced] = env.sent();
+  assert.equal(env.sent().length, 3);
+  assert.equal(initial.eventType, "pageview");
+  assert.equal(initial.route, "/checkout");
+  assert.equal(initial.payload.referrer, "https://google.com/search");
+  assert.equal(pushed.eventType, "pageview");
+  assert.equal(pushed.route, "/pricing");
+  assert.equal(pushed.payload, undefined); // only the initial load carries a referrer
+  assert.equal(replaced.eventType, "pageview");
+  assert.equal(replaced.route, "/pricing/annual");
+
+  // One session for the whole tab, and every event — not just pageviews — carries it.
+  assert.match(initial.sessionId, /^[a-f0-9]{16,64}$/);
+  assert.ok([initial, pushed, replaced].every((event) => event.sessionId === initial.sessionId));
+
+  await Midline.close();
+  delete globalThis.window;
+});
+
+test("browser: capturePageviews: false suppresses pageviews without disabling other capture", async () => {
+  const env = fakeWindow();
+  const { win } = env;
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, capturePageviews: false });
+  win.history.pushState({}, "", "/pricing");
+  Midline.captureMessage("still works");
+  await Midline.flush();
+
+  const events = env.sent();
+  assert.ok(events.every((event) => event.eventType !== "pageview"));
+  assert.equal(events.length, 1);
+  assert.equal(events[0].payload.message, "still works");
+
+  await Midline.close();
+  delete globalThis.window;
+});
+
 test("browser: pending events go out with keepalive when the page is hidden", async () => {
   await withSdk({}, async ({ win, calls }) => {
     Midline.captureMessage("leaving");