midline-agent 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `midline-agent`, compiled from git history. Dates reflect commit dates, newest first.
 
+## 2026-09-21
+- feat: `midlineMiddleware({ trustProxy })` records the end user's IP from `X-Forwarded-For` when the server
+  sits behind a load balancer or CDN, instead of the proxy's address
+- feat: `captureIp: false` (env `MIDLINE_CAPTURE_IP=false`) stops the Node agent recording IP addresses;
+  the browser SDK's `captureIp: false` asks the Midline server not to keep the visitor's (0.7.0)
+
+## 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)

package/README.md

@@ -78,6 +78,21 @@ app.use(midlineErrorHandler()); // after your routes; passes the error on untouc
 app.listen(3000);
 ```
 
+#### Behind a load balancer or CDN
+
+By default the IP recorded for each request is Express's `req.ip`. Behind a load balancer that is the
+load balancer's address, not your user's. Tell the middleware how many proxies sit in front of your server
+and it reads the real address from `X-Forwarded-For`:
+
+```ts
+app.use(midlineMiddleware({ trustProxy: 1 })); // one load balancer or CDN in front
+```
+
+It counts that many hops in from the end of the chain, so an address a client puts in the header
+itself is ignored. Leave it unset if clients reach your server directly, or if you already set
+`app.set("trust proxy", …)` yourself. `trustProxy: true` believes the whole header, which is only safe when
+nothing can reach the server except through your proxies.
+
 ### NestJS
 
 ```ts
@@ -249,6 +264,7 @@ MidlineAgent.init({
   redactFields?: string[],        // added to the built-in list (maskFields still works)
   redactHeaders?: string[],
   captureConsole?: boolean,       // MIDLINE_CAPTURE_CONSOLE — also send what the process prints (off by default)
+  captureIp?: boolean,            // MIDLINE_CAPTURE_IP — record the caller's IP (on by default; false leaves it out)
 
   // Delivery
   flushIntervalMs?: number,       // default 1500
@@ -270,6 +286,7 @@ MidlineAgent.init({
 MIDLINE_API_KEY=...
 MIDLINE_ENDPOINT=https://api.usemidline.com
 # MIDLINE_CAPTURE_CONSOLE=true
+# MIDLINE_CAPTURE_IP=false
 
 # proxy mode
 TARGET_API_URL=http://localhost:4000
@@ -309,6 +326,45 @@ const app = await NestFactory.create(AppModule); // startup lines are captured f
 
 ---
 
+## IP addresses
+
+Request events carry the address of whoever made the request. It shows in the dashboard as the **IP address**
+column on Logs and on the Visitors page's **Recent visitors** table. Where it comes from depends on how you
+connect:
+
+| You use | Address recorded |
+| --- | --- |
+| Express or NestJS middleware | Express's `req.ip`. With `trustProxy`, the client read from `X-Forwarded-For`. |
+| Plain Node `http` middleware | The socket's peer. With `trustProxy`, the client read from `X-Forwarded-For`. |
+| Proxy mode | The socket's peer. With `trustForwardedHeaders`, the first `X-Forwarded-For` entry. |
+| Browser SDK | The address the Midline server saw the browser connect from. Nothing to configure, and any IP the page sends is ignored. |
+
+- **Behind a load balancer or CDN**, set `trustProxy` (see [Express](#behind-a-load-balancer-or-cdn)) or every request shows the
+  proxy's address instead of your user's.
+- **On your own machine** every caller is `::1` or `127.0.0.1`: the address a computer uses for itself. Real addresses
+  appear once real traffic reaches the service.
+- **A self-hosted Midline server** that sits behind a proxy needs `TRUST_PROXY=<number of proxies>` in its own
+  environment, so browser events record the visitor rather than the proxy. Left unset, `X-Forwarded-For` is ignored,
+  which stops a client from choosing the address that is recorded.
+
+### Not recording IP addresses
+
+An IP address can count as personal data. To keep it out entirely:
+
+```ts
+MidlineAgent.init({ apiKey: process.env.MIDLINE_API_KEY, captureIp: false }); // or MIDLINE_CAPTURE_IP=false
+```
+
+```ts
+Midline.init({ apiKey: "pk_…", captureIp: false }); // browser SDK
+```
+
+The Node agent drops the address in your process, so it is never sent. The browser SDK can only ask: the address is read by
+the Midline server, which then doesn't store it. A server that predates 0.7.0 ignores the request, so update a
+self-hosted server before relying on it. Events without an address show "—" in the dashboard.
+
+---
+
 ## Sensitive data
 
 Redaction happens **in your process, before an event is queued**. What's masked never reaches a
@@ -426,6 +482,7 @@ the browser will block the call's preflight.
 | `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. |
+| `captureIp` | `true` | The visitor's IP is read by the Midline server from the connection, not by the browser. `false` asks the server not to keep it. Needs a server that supports it (an older one ignores the request). |
 | `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. |

package/dist/agent.js

@@ -363,7 +363,7 @@ class MidlineAgent {
             timestamp: validTimestamp(event.timestamp),
             // Clamped to the server's validation limits: one over-long field would
             // otherwise get every event rejected.
-            ip: clamp(event.ip, 64),
+            ip: config.captureIp ? clamp(event.ip, 64) : undefined,
             userAgent: clamp(event.userAgent, 512),
             service: clamp(config.serviceName, 128),
             environment: clamp(config.environment, 128),

package/dist/browser/client.js

@@ -82,6 +82,7 @@ function resolve(config) {
         consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
         captureWebVitals: config.captureWebVitals !== false,
         capturePageviews: config.capturePageviews !== false,
+        captureIp: config.captureIp !== false,
         tracePropagationTargets: config.tracePropagationTargets,
         ignoreErrors: config.ignoreErrors ?? [],
         ignoreUrls: config.ignoreUrls ?? [],
@@ -372,6 +373,9 @@ class BrowserClient {
             runtime: "browser",
             page: { url: this.pageUrl(), path: this.currentRoute() },
         };
+        // The IP is read server-side from the connection, so all the SDK can do is ask for it not to be kept.
+        if (!this.config.captureIp)
+            metadata.captureIp = false;
         if (this.user && (this.user.id || this.user.username))
             metadata.user = { ...this.user };
         if (Object.keys(this.tags).length)

package/dist/browser/types.d.ts

@@ -42,6 +42,13 @@ export interface MidlineBrowserConfig {
      * funnel view in the Midline dashboard is built from. Default true.
      */
     capturePageviews?: boolean;
+    /**
+     * Let Midline record the visitor's IP address. Default true. Your visitors' IP is read by the
+     * Midline server from the connection — the browser can't know it — so set this to false to ask
+     * the server not to keep it. Needs a Midline server that supports it; an older one ignores the
+     * request and keeps the address.
+     */
+    captureIp?: 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

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.5.0";
+export declare const BROWSER_SDK_VERSION = "0.7.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.5.0";
+exports.BROWSER_SDK_VERSION = "0.7.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/client-ip.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingMessage } from "http";
+/**
+ * How many reverse proxies (load balancer, CDN) sit between the internet and this server.
+ * `true` trusts the whole `X-Forwarded-For` chain, so the leftmost entry is the client.
+ */
+export type TrustProxy = boolean | number;
+type WithExpressIp = IncomingMessage & {
+    ip?: string;
+};
+/**
+ * The address of whoever called this server.
+ *
+ * Without `trustProxy` this is Express's `req.ip` (which follows the app's own `trust proxy`
+ * setting) or the socket's peer. Behind a load balancer that is the load balancer, not the
+ * user — so with `trustProxy` the client is read from `X-Forwarded-For` instead, counting
+ * `trustProxy` hops in from the end of the chain: the entries a client prepends itself
+ * are ignored, and only what your own proxies appended is believed.
+ */
+export declare function clientIp(req: WithExpressIp, trustProxy?: TrustProxy): string | undefined;
+export {};

package/dist/client-ip.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientIp = clientIp;
+const tap_1 = require("./tap");
+/**
+ * The address of whoever called this server.
+ *
+ * Without `trustProxy` this is Express's `req.ip` (which follows the app's own `trust proxy`
+ * setting) or the socket's peer. Behind a load balancer that is the load balancer, not the
+ * user — so with `trustProxy` the client is read from `X-Forwarded-For` instead, counting
+ * `trustProxy` hops in from the end of the chain: the entries a client prepends itself
+ * are ignored, and only what your own proxies appended is believed.
+ */
+function clientIp(req, trustProxy) {
+    const peer = req.socket?.remoteAddress;
+    if (trustProxy === undefined || trustProxy === false || trustProxy === 0) {
+        return req.ip ?? peer;
+    }
+    const forwarded = ((0, tap_1.headerValue)(req.headers["x-forwarded-for"]) ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const chain = peer ? [...forwarded, peer] : forwarded;
+    if (!chain.length) {
+        return undefined;
+    }
+    const index = trustProxy === true ? 0 : Math.max(0, chain.length - 1 - trustProxy);
+    return chain[index];
+}

package/dist/config.d.ts

@@ -27,6 +27,7 @@ export interface ResolvedConfig {
     redactHeaders: string[];
     capture: ResolvedCapture;
     captureConsole: boolean;
+    captureIp: boolean;
     onError?: (message: string) => void;
     debug: boolean;
     flushIntervalMs: number;

package/dist/config.js

@@ -205,6 +205,7 @@ function resolveConfig(config) {
         redactHeaders: config.redactHeaders ?? [],
         capture: resolveCapture(config.capture),
         captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
+        captureIp: config.captureIp ?? envFlag("MIDLINE_CAPTURE_IP") ?? true,
         onError: config.onError,
         debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
         flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60000),

package/dist/esm/browser/client.js

@@ -76,6 +76,7 @@ function resolve(config) {
         consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
         captureWebVitals: config.captureWebVitals !== false,
         capturePageviews: config.capturePageviews !== false,
+        captureIp: config.captureIp !== false,
         tracePropagationTargets: config.tracePropagationTargets,
         ignoreErrors: config.ignoreErrors ?? [],
         ignoreUrls: config.ignoreUrls ?? [],
@@ -366,6 +367,9 @@ export class BrowserClient {
             runtime: "browser",
             page: { url: this.pageUrl(), path: this.currentRoute() },
         };
+        // The IP is read server-side from the connection, so all the SDK can do is ask for it not to be kept.
+        if (!this.config.captureIp)
+            metadata.captureIp = false;
         if (this.user && (this.user.id || this.user.username))
             metadata.user = { ...this.user };
         if (Object.keys(this.tags).length)

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.5.0";
+export const BROWSER_SDK_VERSION = "0.7.0";

package/dist/middleware.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "http";
 import { MidlineAgent } from "./agent";
+import { TrustProxy } from "./client-ip";
 import { CaptureOptions } from "./types";
 export interface MidlineMiddlewareOptions {
     /** Defaults to the agent created by `MidlineAgent.init()`, looked up per request. */
@@ -8,6 +9,14 @@ export interface MidlineMiddlewareOptions {
     capture?: CaptureOptions;
     /** Return true to leave a request out, e.g. health checks. */
     ignore?: (req: IncomingMessage) => boolean;
+    /**
+     * How many reverse proxies (load balancer, CDN) sit in front of this server. Set it so the
+     * recorded IP is the end user's rather than the proxy's; `1` for one load balancer. Left unset,
+     * the address is Express's `req.ip`, which follows your app's own `trust proxy` setting.
+     * `true` trusts the whole `X-Forwarded-For` chain — only safe if nothing reaches the server
+     * except through your proxies, since a client could otherwise claim any address.
+     */
+    trustProxy?: TrustProxy;
 }
 /**
  * Records every request that passes through. Mount it before your routes.

package/dist/middleware.js

@@ -4,6 +4,7 @@ exports.midlineMiddleware = midlineMiddleware;
 const agent_1 = require("./agent");
 const breadcrumbs_1 = require("./breadcrumbs");
 const config_1 = require("./config");
+const client_ip_1 = require("./client-ip");
 const context_1 = require("./context");
 const tap_1 = require("./tap");
 /**
@@ -59,7 +60,7 @@ function observe(req, res, options, captureOverride) {
                 url,
                 statusCode,
                 durationMs: Number(process.hrtime.bigint() - started) / 1e6,
-                ip: req.ip ?? req.socket?.remoteAddress,
+                ip: (0, client_ip_1.clientIp)(req, options.trustProxy),
                 userAgent: (0, tap_1.headerValue)(req.headers["user-agent"]),
                 routeTemplate: typeof routePath === "string" ? `${req.baseUrl ?? ""}${routePath}` : undefined,
                 aborted,

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/dist/types.d.ts

@@ -62,6 +62,12 @@ export interface MidlineConfig {
      * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
      */
     captureConsole?: boolean;
+    /**
+     * Record the caller's IP address on request events. Default true. Set to false to
+     * leave it out entirely, e.g. where IPs count as personal data you don't want to hold:
+     * the address is dropped in this process and never sent. Env fallback: `MIDLINE_CAPTURE_IP`.
+     */
+    captureIp?: boolean;
     /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
     enabled?: boolean;
     /**

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "midline-agent",
-  "version": "0.5.0",
-  "description": "Midline — request, error and security monitoring for Node, and error, network, Web Vitals and pageview/visitor monitoring for browsers",
+  "version": "0.7.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/agent.ts

@@ -433,7 +433,7 @@ export class MidlineAgent {
       timestamp: validTimestamp(event.timestamp),
       // Clamped to the server's validation limits: one over-long field would
       // otherwise get every event rejected.
-      ip: clamp(event.ip, 64),
+      ip: config.captureIp ? clamp(event.ip, 64) : undefined,
       userAgent: clamp(event.userAgent, 512),
       service: clamp(config.serviceName, 128),
       environment: clamp(config.environment, 128),

package/src/browser/client.ts

@@ -59,6 +59,7 @@ interface Resolved {
   consoleLevels: ConsoleLevel[];
   captureWebVitals: boolean;
   capturePageviews: boolean;
+  captureIp: boolean;
   tracePropagationTargets?: Array<string | RegExp>;
   ignoreErrors: Array<string | RegExp>;
   ignoreUrls: Array<string | RegExp>;
@@ -126,6 +127,7 @@ function resolve(config: MidlineBrowserConfig): Resolved {
     consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
     captureWebVitals: config.captureWebVitals !== false,
     capturePageviews: config.capturePageviews !== false,
+    captureIp: config.captureIp !== false,
     tracePropagationTargets: config.tracePropagationTargets,
     ignoreErrors: config.ignoreErrors ?? [],
     ignoreUrls: config.ignoreUrls ?? [],
@@ -454,6 +456,8 @@ export class BrowserClient {
       runtime: "browser",
       page: { url: this.pageUrl(), path: this.currentRoute() },
     };
+    // The IP is read server-side from the connection, so all the SDK can do is ask for it not to be kept.
+    if (!this.config.captureIp) metadata.captureIp = false;
     if (this.user && (this.user.id || this.user.username)) metadata.user = { ...this.user };
     if (Object.keys(this.tags).length) metadata.tags = { ...this.tags };
     const nav = this.win.navigator;

package/src/browser/types.ts

@@ -48,6 +48,13 @@ export interface MidlineBrowserConfig {
    * funnel view in the Midline dashboard is built from. Default true.
    */
   capturePageviews?: boolean;
+  /**
+   * Let Midline record the visitor's IP address. Default true. Your visitors' IP is read by the
+   * Midline server from the connection — the browser can't know it — so set this to false to ask
+   * the server not to keep it. Needs a Midline server that supports it; an older one ignores the
+   * request and keeps the address.
+   */
+  captureIp?: boolean;
 
   /**
    * Requests that get a W3C `traceparent` header, so the backend's midline-agent

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.5.0";
+export const BROWSER_SDK_VERSION = "0.7.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/client-ip.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage } from "http";
+import { headerValue } from "./tap";
+
+/**
+ * How many reverse proxies (load balancer, CDN) sit between the internet and this server.
+ * `true` trusts the whole `X-Forwarded-For` chain, so the leftmost entry is the client.
+ */
+export type TrustProxy = boolean | number;
+
+type WithExpressIp = IncomingMessage & { ip?: string };
+
+/**
+ * The address of whoever called this server.
+ *
+ * Without `trustProxy` this is Express's `req.ip` (which follows the app's own `trust proxy`
+ * setting) or the socket's peer. Behind a load balancer that is the load balancer, not the
+ * user — so with `trustProxy` the client is read from `X-Forwarded-For` instead, counting
+ * `trustProxy` hops in from the end of the chain: the entries a client prepends itself
+ * are ignored, and only what your own proxies appended is believed.
+ */
+export function clientIp(req: WithExpressIp, trustProxy?: TrustProxy): string | undefined {
+  const peer = req.socket?.remoteAddress;
+  if (trustProxy === undefined || trustProxy === false || trustProxy === 0) {
+    return req.ip ?? peer;
+  }
+
+  const forwarded = (headerValue(req.headers["x-forwarded-for"]) ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const chain = peer ? [...forwarded, peer] : forwarded;
+  if (!chain.length) {
+    return undefined;
+  }
+
+  const index = trustProxy === true ? 0 : Math.max(0, chain.length - 1 - trustProxy);
+  return chain[index];
+}

package/src/config.ts

@@ -37,6 +37,7 @@ export interface ResolvedConfig {
   redactHeaders: string[];
   capture: ResolvedCapture;
   captureConsole: boolean;
+  captureIp: boolean;
   onError?: (message: string) => void;
   debug: boolean;
   flushIntervalMs: number;
@@ -209,6 +210,7 @@ export function resolveConfig(config: MidlineConfig): ResolvedConfig {
     redactHeaders: config.redactHeaders ?? [],
     capture: resolveCapture(config.capture),
     captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
+    captureIp: config.captureIp ?? envFlag("MIDLINE_CAPTURE_IP") ?? true,
     onError: config.onError,
     debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
     flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60_000),

package/src/middleware.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "http";
 import { MidlineAgent } from "./agent";
 import { addBreadcrumb } from "./breadcrumbs";
 import { ResolvedCapture, resolveCapture } from "./config";
+import { clientIp, TrustProxy } from "./client-ip";
 import { createRequestContext, setRequestContext } from "./context";
 import { BodyTap, headerValue, isCompressed } from "./tap";
 import { CaptureOptions } from "./types";
@@ -13,6 +14,14 @@ export interface MidlineMiddlewareOptions {
   capture?: CaptureOptions;
   /** Return true to leave a request out, e.g. health checks. */
   ignore?: (req: IncomingMessage) => boolean;
+  /**
+   * How many reverse proxies (load balancer, CDN) sit in front of this server. Set it so the
+   * recorded IP is the end user's rather than the proxy's; `1` for one load balancer. Left unset,
+   * the address is Express's `req.ip`, which follows your app's own `trust proxy` setting.
+   * `true` trusts the whole `X-Forwarded-For` chain — only safe if nothing reaches the server
+   * except through your proxies, since a client could otherwise claim any address.
+   */
+  trustProxy?: TrustProxy;
 }
 
 /** The Express additions this reads when they exist. Plain `http` requests work too. */
@@ -87,7 +96,7 @@ function observe(
         url,
         statusCode,
         durationMs: Number(process.hrtime.bigint() - started) / 1e6,
-        ip: req.ip ?? req.socket?.remoteAddress,
+        ip: clientIp(req, options.trustProxy),
         userAgent: headerValue(req.headers["user-agent"]),
         routeTemplate: typeof routePath === "string" ? `${req.baseUrl ?? ""}${routePath}` : undefined,
         aborted,

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/src/types.ts

@@ -69,6 +69,12 @@ export interface MidlineConfig {
    * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
    */
   captureConsole?: boolean;
+  /**
+   * Record the caller's IP address on request events. Default true. Set to false to
+   * leave it out entirely, e.g. where IPs count as personal data you don't want to hold:
+   * the address is dropped in this process and never sent. Env fallback: `MIDLINE_CAPTURE_IP`.
+   */
+  captureIp?: boolean;
 
   /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
   enabled?: boolean;

package/test/browser.test.js

@@ -277,6 +277,19 @@ test("browser: user, tags and a rate limit", async () => {
   });
 });
 
+test("browser: captureIp false asks the server not to keep the IP, and is otherwise silent", async () => {
+  await withSdk({}, async ({ sent }) => {
+    Midline.captureMessage("default");
+    await Midline.flush();
+    assert.equal("captureIp" in sent()[0].metadata, false);
+  });
+  await withSdk({ captureIp: false }, async ({ sent }) => {
+    Midline.captureMessage("private");
+    await Midline.flush();
+    assert.equal(sent()[0].metadata.captureIp, false);
+  });
+});
+
 test("browser: console capture is opt-in and never loops", async () => {
   await withSdk({ captureConsole: true }, async ({ win, sent }) => {
     win.console.error("payment failed", { token: "secret-token", amount: 5 });

package/test/middleware.test.js

@@ -176,3 +176,75 @@ test("plain node http servers work with the same middleware", async () => {
     await collector.close();
   }
 });
+
+test("express: the recorded IP is the end user's when trustProxy says how many proxies are in front", async () => {
+  const collector = await startSocketCollector();
+  const agent = new MidlineAgent({ apiKey: "ak_ip", endpoint: collector.url, flushIntervalMs: 60_000 });
+
+  const serve = async (options) => {
+    const app = express();
+    app.use(midlineMiddleware({ agent, ...options }));
+    app.get("/ping", (_req, res) => res.json({ ok: true }));
+    return listen(app);
+  };
+  const ipAfter = async (server, headers) => {
+    const before = collector.events().length;
+    await request(`http://127.0.0.1:${server.port}/ping`, { headers });
+    await waitFor(() => agent.queued > 0);
+    await agent.flush();
+    return collector.events().slice(before).pop().ip;
+  };
+
+  const plain = await serve({});
+  const oneProxy = await serve({ trustProxy: 1 });
+  const wholeChain = await serve({ trustProxy: true });
+
+  try {
+    // No trustProxy and no Express setting: the address the socket saw, never the header.
+    assert.match(await ipAfter(plain, { "x-forwarded-for": "203.0.113.50" }), /127\.0\.0\.1$/);
+    // One proxy in front: the address it appended, not what the client prepended.
+    assert.equal(await ipAfter(oneProxy, { "x-forwarded-for": "6.6.6.6, 203.0.113.50" }), "203.0.113.50");
+    assert.equal(await ipAfter(oneProxy, { "x-forwarded-for": "203.0.113.50" }), "203.0.113.50");
+    // No header at all: falls back to the socket peer.
+    assert.match(await ipAfter(oneProxy, {}), /127\.0\.0\.1$/);
+    assert.equal(await ipAfter(wholeChain, { "x-forwarded-for": "203.0.113.50, 10.0.0.1" }), "203.0.113.50");
+  } finally {
+    agent.close();
+    await Promise.all([plain.close(), oneProxy.close(), wholeChain.close(), collector.close()]);
+  }
+});
+
+test("express: captureIp false keeps the caller's address out of every event", async () => {
+  const collector = await startSocketCollector();
+  const record = async (options) => {
+    const agent = new MidlineAgent({ apiKey: "ak_noip", endpoint: collector.url, flushIntervalMs: 60_000, ...options });
+    const app = express();
+    app.use(midlineMiddleware({ agent }));
+    app.get("/ping", (_req, res) => res.json({ ok: true }));
+    const server = await listen(app);
+    try {
+      const before = collector.events().length;
+      await request(`http://127.0.0.1:${server.port}/ping`);
+      await waitFor(() => agent.queued > 0);
+      await agent.flush();
+      return collector.events().slice(before).pop();
+    } finally {
+      agent.close();
+      await server.close();
+    }
+  };
+
+  try {
+    assert.match((await record({})).ip, /127\.0\.0\.1$/);
+    assert.equal((await record({ captureIp: false })).ip, undefined);
+
+    process.env.MIDLINE_CAPTURE_IP = "false";
+    try {
+      assert.equal((await record({})).ip, undefined);
+    } finally {
+      delete process.env.MIDLINE_CAPTURE_IP;
+    }
+  } finally {
+    await collector.close();
+  }
+});

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 });
+});