midline-agent 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `midline-agent`, compiled from git history. Dates reflect commit dates, newest first.
+
+## 2026-09-20
+- feat: `midline-agent sourcemaps upload <dir> --release <name>` uploads a build's source maps to Midline
+  so stack traces show original code. Authenticates with a project server API key; browser keys are refused
+  (0.6.0)
+
+## 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.6.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.6.0";

package/dist/cli.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const agent_1 = require("./agent");
 const config_1 = require("./config");
 const proxy_1 = require("./proxy");
+const sourcemaps_1 = require("./sourcemaps");
 const USAGE = `Usage: midline-agent proxy [--target <url>] [--port <n>] [--host <addr>]
 
 Forwards traffic to a destination API and reports every exchange to Midline.
@@ -17,6 +18,18 @@ Midline server:
   MIDLINE_ENDPOINT     default https://api.usemidline.com
   MIDLINE_CUSTOM_CA    extra CA for the Midline server only (PEM or file path)
   TARGET_API_CA        extra CA for the destination only (PEM or file path)
+
+Usage: midline-agent sourcemaps upload <dir> --release <name> [--url-prefix <prefix>] [--dry-run]
+
+Uploads every .map file under <dir> so stack traces from that release show your
+original code. Run it in CI after your build, with the same release name your SDK
+reports.
+
+  --release      Release the build belongs to        (required)
+  --url-prefix   What the built files are served under (default "~", any origin)
+  --endpoint     Midline server                      (MIDLINE_ENDPOINT)
+  --api-key      A project SERVER key, pk_ keys are refused (MIDLINE_API_KEY)
+  --dry-run      List what would be uploaded
 `;
 function flag(args, name) {
     const index = args.indexOf(`--${name}`);
@@ -25,8 +38,30 @@ function flag(args, name) {
     const inline = args.find((arg) => arg.startsWith(`--${name}=`));
     return inline?.slice(name.length + 3);
 }
+async function sourcemaps(args) {
+    const dir = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
+    if (args[1] !== "upload" || !dir || args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(USAGE);
+        process.exitCode = args.includes("--help") || args.includes("-h") ? 0 : 1;
+        return;
+    }
+    const result = await (0, sourcemaps_1.uploadSourceMaps)({
+        dir,
+        release: flag(args, "release") ?? "",
+        urlPrefix: flag(args, "url-prefix"),
+        endpoint: flag(args, "endpoint"),
+        apiKey: flag(args, "api-key"),
+        dryRun: args.includes("--dry-run"),
+        log: (line) => process.stdout.write(`midline sourcemaps: ${line}\n`),
+    });
+    process.stdout.write(`midline sourcemaps: ${result.uploaded.length} ${args.includes("--dry-run") ? "listed" : "uploaded"}, ${result.failed.length} failed\n`);
+    if (result.failed.length)
+        process.exitCode = 1;
+}
 async function main() {
     const args = process.argv.slice(2);
+    if (args[0] === "sourcemaps")
+        return sourcemaps(args);
     if (args[0] !== "proxy" || args.includes("--help") || args.includes("-h")) {
         process.stdout.write(USAGE);
         process.exitCode = args[0] === "proxy" || args.length === 0 ? 0 : 1;
@@ -58,6 +93,6 @@ async function main() {
     process.on("SIGTERM", () => stop("SIGTERM"));
 }
 main().catch((err) => {
-    process.stderr.write(`midline proxy: ${err instanceof config_1.ConfigError ? err.message : err?.stack ?? err}\n`);
+    process.stderr.write(`midline ${process.argv[2] === "sourcemaps" ? "sourcemaps" : "proxy"}: ${err instanceof config_1.ConfigError ? err.message : err?.stack ?? err}\n`);
     process.exit(1);
 });

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.6.0";

package/dist/sourcemaps.d.ts

@@ -0,0 +1,26 @@
+export interface UploadOptions {
+    /** Directory containing the build output (searched recursively for `*.map`). */
+    dir: string;
+    /** The release the build belongs to: the same string passed as `release` to the SDK. */
+    release: string;
+    /** What the built files are served under. Default `~`, meaning "any origin, this path". */
+    urlPrefix?: string;
+    /** Midline server. Env fallback: `MIDLINE_ENDPOINT`. */
+    endpoint?: string;
+    /** A project's **server** API key. Env fallback: `MIDLINE_API_KEY`. Browser keys are refused by the server. */
+    apiKey?: string;
+    dryRun?: boolean;
+    log?: (line: string) => void;
+}
+export interface UploadResult {
+    uploaded: string[];
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** Every `*.map` under `dir`, without descending into node_modules. */
+export declare function findMaps(dir: string, depth?: number): Promise<string[]>;
+/** `dist/assets/app-3f2a.js.map` -> `~/assets/app-3f2a.js`: the built file the map describes, as the server will match it. */
+export declare function uploadName(dir: string, mapFile: string, urlPrefix?: string): string;
+export declare function uploadSourceMaps(options: UploadOptions): Promise<UploadResult>;

package/dist/sourcemaps.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findMaps = findMaps;
+exports.uploadName = uploadName;
+exports.uploadSourceMaps = uploadSourceMaps;
+const promises_1 = require("fs/promises");
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const MAX_DEPTH = 20;
+const CONCURRENCY = 4;
+/** Every `*.map` under `dir`, without descending into node_modules. */
+async function findMaps(dir, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return [];
+    const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+    const found = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name !== "node_modules")
+                found.push(...(await findMaps(full, depth + 1)));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".map")) {
+            found.push(full);
+        }
+    }
+    return found.sort();
+}
+/** `dist/assets/app-3f2a.js.map` -> `~/assets/app-3f2a.js`: the built file the map describes, as the server will match it. */
+function uploadName(dir, mapFile, urlPrefix = "~") {
+    const relative = path.relative(dir, mapFile).split(path.sep).join("/").replace(/\.map$/, "");
+    return `${urlPrefix.replace(/\/+$/, "")}/${relative}`;
+}
+async function uploadSourceMaps(options) {
+    const log = options.log ?? (() => undefined);
+    if (!options.release?.trim())
+        throw new config_1.ConfigError("--release is required");
+    const apiKey = options.apiKey ?? (0, config_1.env)("MIDLINE_API_KEY");
+    if (!apiKey && !options.dryRun)
+        throw new config_1.ConfigError("Set MIDLINE_API_KEY (a project server key) or pass --api-key");
+    const origin = (0, config_1.resolveEndpointOrigin)(options.endpoint ?? (0, config_1.env)("MIDLINE_ENDPOINT") ?? config_1.DEFAULT_ENDPOINT);
+    const maps = await findMaps(options.dir).catch((error) => {
+        if (error.code === "ENOENT" || error.code === "ENOTDIR")
+            throw new config_1.ConfigError(`${options.dir} is not a directory`);
+        throw error;
+    });
+    if (!maps.length)
+        throw new config_1.ConfigError(`No .map files found under ${options.dir}. Enable source maps in your build.`);
+    const result = { uploaded: [], failed: [] };
+    const queue = [...maps];
+    const worker = async () => {
+        for (let file = queue.shift(); file; file = queue.shift()) {
+            const name = uploadName(options.dir, file, options.urlPrefix);
+            if (options.dryRun) {
+                log(`would upload ${name}`);
+                result.uploaded.push(name);
+                continue;
+            }
+            try {
+                const body = new FormData();
+                body.append("release", options.release);
+                body.append("name", name);
+                body.append("file", new Blob([await (0, promises_1.readFile)(file)]), path.basename(file));
+                const response = await fetch(new URL("/api/sourcemaps/upload", origin), {
+                    method: "POST",
+                    headers: { "x-midline-key": apiKey },
+                    body,
+                });
+                if (!response.ok) {
+                    const detail = await response.json().catch(() => undefined);
+                    throw new Error(`${response.status} ${detail?.message ?? response.statusText}`);
+                }
+                log(`uploaded ${name}`);
+                result.uploaded.push(name);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                log(`failed   ${name}: ${message}`);
+                result.failed.push({ name, error: message });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, maps.length) }, worker));
+    return result;
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "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.6.0",
+  "description": "Midline \u2014 request, error and security monitoring for Node, and error, network, Web Vitals and pageview/visitor monitoring for browsers",
+  "homepage": "https://usemidline.com",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -38,16 +39,32 @@
   },
   "keywords": [
     "midline",
+    "api-monitoring",
+    "api-observability",
+    "apm",
+    "browser",
+    "console-capture",
+    "error-tracking",
+    "errors",
     "express",
+    "express-middleware",
+    "frontend",
+    "http-logging",
+    "issue-tracking",
+    "log-redaction",
     "monitoring",
+    "nestjs",
+    "nodejs",
+    "observability",
+    "proxy",
+    "real-user-monitoring",
+    "request",
+    "request-logging",
+    "reverse-proxy",
+    "rum",
     "sdk",
     "security",
-    "request",
-    "errors",
-    "proxy",
-    "browser",
-    "web-vitals",
-    "frontend"
+    "web-vitals"
   ],
   "author": "Your Name",
   "license": "MIT",

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.6.0";

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { MidlineAgent } from "./agent";
 import { ConfigError } from "./config";
 import { proxyAddress, resolveTarget, startMidlineProxy } from "./proxy";
+import { uploadSourceMaps } from "./sourcemaps";
 
 const USAGE = `Usage: midline-agent proxy [--target <url>] [--port <n>] [--host <addr>]
 
@@ -16,6 +17,18 @@ Midline server:
   MIDLINE_ENDPOINT     default https://api.usemidline.com
   MIDLINE_CUSTOM_CA    extra CA for the Midline server only (PEM or file path)
   TARGET_API_CA        extra CA for the destination only (PEM or file path)
+
+Usage: midline-agent sourcemaps upload <dir> --release <name> [--url-prefix <prefix>] [--dry-run]
+
+Uploads every .map file under <dir> so stack traces from that release show your
+original code. Run it in CI after your build, with the same release name your SDK
+reports.
+
+  --release      Release the build belongs to        (required)
+  --url-prefix   What the built files are served under (default "~", any origin)
+  --endpoint     Midline server                      (MIDLINE_ENDPOINT)
+  --api-key      A project SERVER key, pk_ keys are refused (MIDLINE_API_KEY)
+  --dry-run      List what would be uploaded
 `;
 
 function flag(args: string[], name: string): string | undefined {
@@ -25,8 +38,29 @@ function flag(args: string[], name: string): string | undefined {
   return inline?.slice(name.length + 3);
 }
 
+async function sourcemaps(args: string[]): Promise<void> {
+  const dir = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
+  if (args[1] !== "upload" || !dir || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    process.exitCode = args.includes("--help") || args.includes("-h") ? 0 : 1;
+    return;
+  }
+  const result = await uploadSourceMaps({
+    dir,
+    release: flag(args, "release") ?? "",
+    urlPrefix: flag(args, "url-prefix"),
+    endpoint: flag(args, "endpoint"),
+    apiKey: flag(args, "api-key"),
+    dryRun: args.includes("--dry-run"),
+    log: (line) => process.stdout.write(`midline sourcemaps: ${line}\n`),
+  });
+  process.stdout.write(`midline sourcemaps: ${result.uploaded.length} ${args.includes("--dry-run") ? "listed" : "uploaded"}, ${result.failed.length} failed\n`);
+  if (result.failed.length) process.exitCode = 1;
+}
+
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
+  if (args[0] === "sourcemaps") return sourcemaps(args);
   if (args[0] !== "proxy" || args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
     process.exitCode = args[0] === "proxy" || args.length === 0 ? 0 : 1;
@@ -64,6 +98,6 @@ async function main(): Promise<void> {
 }
 
 main().catch((err) => {
-  process.stderr.write(`midline proxy: ${err instanceof ConfigError ? err.message : err?.stack ?? err}\n`);
+  process.stderr.write(`midline ${process.argv[2] === "sourcemaps" ? "sourcemaps" : "proxy"}: ${err instanceof ConfigError ? err.message : err?.stack ?? err}\n`);
   process.exit(1);
 });

package/src/sourcemaps.ts

@@ -0,0 +1,99 @@
+import { readdir, readFile } from "fs/promises";
+import * as path from "path";
+import { DEFAULT_ENDPOINT, ConfigError, env, resolveEndpointOrigin } from "./config";
+
+export interface UploadOptions {
+  /** Directory containing the build output (searched recursively for `*.map`). */
+  dir: string;
+  /** The release the build belongs to: the same string passed as `release` to the SDK. */
+  release: string;
+  /** What the built files are served under. Default `~`, meaning "any origin, this path". */
+  urlPrefix?: string;
+  /** Midline server. Env fallback: `MIDLINE_ENDPOINT`. */
+  endpoint?: string;
+  /** A project's **server** API key. Env fallback: `MIDLINE_API_KEY`. Browser keys are refused by the server. */
+  apiKey?: string;
+  dryRun?: boolean;
+  log?: (line: string) => void;
+}
+
+export interface UploadResult {
+  uploaded: string[];
+  failed: Array<{ name: string; error: string }>;
+}
+
+const MAX_DEPTH = 20;
+const CONCURRENCY = 4;
+
+/** Every `*.map` under `dir`, without descending into node_modules. */
+export async function findMaps(dir: string, depth = 0): Promise<string[]> {
+  if (depth > MAX_DEPTH) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const found: string[] = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== "node_modules") found.push(...(await findMaps(full, depth + 1)));
+    } else if (entry.isFile() && entry.name.endsWith(".map")) {
+      found.push(full);
+    }
+  }
+  return found.sort();
+}
+
+/** `dist/assets/app-3f2a.js.map` -> `~/assets/app-3f2a.js`: the built file the map describes, as the server will match it. */
+export function uploadName(dir: string, mapFile: string, urlPrefix = "~"): string {
+  const relative = path.relative(dir, mapFile).split(path.sep).join("/").replace(/\.map$/, "");
+  return `${urlPrefix.replace(/\/+$/, "")}/${relative}`;
+}
+
+export async function uploadSourceMaps(options: UploadOptions): Promise<UploadResult> {
+  const log = options.log ?? (() => undefined);
+  if (!options.release?.trim()) throw new ConfigError("--release is required");
+  const apiKey = options.apiKey ?? env("MIDLINE_API_KEY");
+  if (!apiKey && !options.dryRun) throw new ConfigError("Set MIDLINE_API_KEY (a project server key) or pass --api-key");
+  const origin = resolveEndpointOrigin(options.endpoint ?? env("MIDLINE_ENDPOINT") ?? DEFAULT_ENDPOINT);
+
+  const maps = await findMaps(options.dir).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") throw new ConfigError(`${options.dir} is not a directory`);
+    throw error;
+  });
+  if (!maps.length) throw new ConfigError(`No .map files found under ${options.dir}. Enable source maps in your build.`);
+
+  const result: UploadResult = { uploaded: [], failed: [] };
+  const queue = [...maps];
+
+  const worker = async () => {
+    for (let file = queue.shift(); file; file = queue.shift()) {
+      const name = uploadName(options.dir, file, options.urlPrefix);
+      if (options.dryRun) {
+        log(`would upload ${name}`);
+        result.uploaded.push(name);
+        continue;
+      }
+      try {
+        const body = new FormData();
+        body.append("release", options.release);
+        body.append("name", name);
+        body.append("file", new Blob([await readFile(file)]), path.basename(file));
+        const response = await fetch(new URL("/api/sourcemaps/upload", origin), {
+          method: "POST",
+          headers: { "x-midline-key": apiKey as string },
+          body,
+        });
+        if (!response.ok) {
+          const detail = await response.json().catch(() => undefined);
+          throw new Error(`${response.status} ${detail?.message ?? response.statusText}`);
+        }
+        log(`uploaded ${name}`);
+        result.uploaded.push(name);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`failed   ${name}: ${message}`);
+        result.failed.push({ name, error: message });
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, maps.length) }, worker));
+  return result;
+}

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");

package/test/sourcemaps.test.js

@@ -0,0 +1,71 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const http = require("http");
+const os = require("os");
+const path = require("path");
+const { findMaps, uploadName, uploadSourceMaps } = require("../dist/sourcemaps");
+
+function makeBuild() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "midline-maps-"));
+  fs.mkdirSync(path.join(dir, "assets"));
+  fs.mkdirSync(path.join(dir, "node_modules", "dep"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "assets", "app-1.js.map"), '{"version":3,"mappings":"AAAA"}');
+  fs.writeFileSync(path.join(dir, "main.js.map"), '{"version":3,"mappings":"AAAA"}');
+  fs.writeFileSync(path.join(dir, "assets", "app-1.js"), "//");
+  fs.writeFileSync(path.join(dir, "node_modules", "dep", "x.js.map"), "{}");
+  return dir;
+}
+
+test("finds .map files, skipping node_modules, and names them by the built file they describe", async () => {
+  const dir = makeBuild();
+  const maps = await findMaps(dir);
+  assert.deepEqual(maps.map((m) => path.relative(dir, m)), [path.join("assets", "app-1.js.map"), "main.js.map"]);
+  assert.equal(uploadName(dir, maps[0]), "~/assets/app-1.js");
+  assert.equal(uploadName(dir, maps[1], "https://app.example.com/static/"), "https://app.example.com/static/main.js");
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test("uploads each map with the key, release and name, and reports failures", async () => {
+  const dir = makeBuild();
+  const seen = [];
+  const server = http.createServer((req, res) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      seen.push({ url: req.url, key: req.headers["x-midline-key"], body });
+      const failing = body.includes("main.js");
+      res.writeHead(failing ? 400 : 201, { "content-type": "application/json" });
+      res.end(JSON.stringify(failing ? { message: "That is not a version 3 source map" } : { ok: true }));
+    });
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const endpoint = `http://127.0.0.1:${server.address().port}`;
+
+  const lines = [];
+  const result = await uploadSourceMaps({ dir, release: "1.2.3", endpoint, apiKey: "ak_test", log: (l) => lines.push(l) });
+  server.close();
+
+  assert.equal(seen.length, 2);
+  assert.ok(seen.every((s) => s.url === "/api/sourcemaps/upload" && s.key === "ak_test"));
+  assert.ok(seen.some((s) => s.body.includes("~/assets/app-1.js") && s.body.includes("1.2.3")));
+  assert.deepEqual(result.uploaded, ["~/assets/app-1.js"]);
+  assert.equal(result.failed.length, 1);
+  assert.match(result.failed[0].error, /400 That is not a version 3 source map/);
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test("dry run touches nothing, and misconfiguration fails clearly", async () => {
+  const dir = makeBuild();
+  const dry = await uploadSourceMaps({ dir, release: "1", dryRun: true });
+  assert.equal(dry.uploaded.length, 2);
+  await assert.rejects(uploadSourceMaps({ dir, release: "" }), /--release is required/);
+  await assert.rejects(uploadSourceMaps({ dir, release: "1", apiKey: "k", endpoint: "http://example.com" }), /https/);
+  await assert.rejects(uploadSourceMaps({ dir: os.tmpdir() + "/does-not-exist-midline", release: "1", apiKey: "k", endpoint: "https://api.example.com" }));
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), "midline-empty-"));
+  await assert.rejects(uploadSourceMaps({ dir: empty, release: "1", apiKey: "k", endpoint: "https://api.example.com" }), /No \.map files/);
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.rmSync(empty, { recursive: true, force: true });
+});