midline-agent 0.4.0 → 0.5.0

package/dist/socket-transport.d.ts

@@ -0,0 +1,58 @@
+/** Mirrors midline-core-api/src/realtime/ingest-protocol.ts's IngestAck. Duplicated,
+ * not shared: the two are separate packages, kept in sync by wire convention. */
+export type IngestAckErrorCode = "unauthorized" | "forbidden" | "rate_limited" | "bad_request" | "too_large" | "internal_error";
+export interface IngestAckOk {
+    ok: true;
+    accepted: number;
+    rejected: number;
+}
+export interface IngestAckError {
+    ok: false;
+    code: IngestAckErrorCode;
+    message: string;
+    retryAfterMs?: number;
+}
+export type IngestAck = IngestAckOk | IngestAckError;
+export interface SocketTransportOptions {
+    apiKey: string;
+    /** Full trust store for the Midline endpoint, or undefined for Node's default. */
+    ca?: Array<string | Buffer>;
+    connectTimeoutMs: number;
+    /** Per-emit ack timeout. */
+    timeoutMs: number;
+    /** Reconnection backoff bounds, derived from the agent's own flush/backoff config (see agent.ts). */
+    reconnectionDelayMs: number;
+    reconnectionDelayMaxMs: number;
+    /** Nothing queued for this long -> disconnect; reconnects lazily on the next send(). */
+    idleDisconnectMs: number;
+    userAgent: string;
+}
+/** A transport failure with a stable `code`, matching what agent.ts's errorCode()/describe() expect. */
+export declare class TransportError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Owns one socket.io-client connection to the ingest gateway: connects lazily on
+ * first send, lets socket.io-client's own reconnection/backoff handle transport
+ * drops, and disconnects after a sustained idle period (autoUnref also unrefs the
+ * underlying socket, so — as with the old HTTP transport — telemetry alone never
+ * keeps the process alive; the idle disconnect is extra hygiene on top of that,
+ * not the only thing standing between this and a hung process).
+ */
+export declare class SocketTransport {
+    private readonly origin;
+    private readonly options;
+    private socket;
+    private connecting;
+    private idleTimer;
+    constructor(origin: URL, options: SocketTransportOptions);
+    /** Sends one batch, connecting first if needed. Resolves with the server's ack or throws. */
+    send(events: Array<Record<string, unknown>>): Promise<IngestAck>;
+    destroy(): void;
+    private ensureConnected;
+    private createSocket;
+    private emit;
+    private scheduleIdleDisconnect;
+    private clearIdleTimer;
+}

package/dist/socket-transport.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketTransport = exports.TransportError = void 0;
+const socket_io_client_1 = require("socket.io-client");
+const INGEST_NAMESPACE = "/ingest";
+const INGEST_EVENT = "ingest";
+/** A transport failure with a stable `code`, matching what agent.ts's errorCode()/describe() expect. */
+class TransportError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "TransportError";
+    }
+}
+exports.TransportError = TransportError;
+/**
+ * Owns one socket.io-client connection to the ingest gateway: connects lazily on
+ * first send, lets socket.io-client's own reconnection/backoff handle transport
+ * drops, and disconnects after a sustained idle period (autoUnref also unrefs the
+ * underlying socket, so — as with the old HTTP transport — telemetry alone never
+ * keeps the process alive; the idle disconnect is extra hygiene on top of that,
+ * not the only thing standing between this and a hung process).
+ */
+class SocketTransport {
+    constructor(origin, options) {
+        this.origin = origin;
+        this.options = options;
+        this.socket = null;
+        this.connecting = null;
+        this.idleTimer = null;
+    }
+    /** Sends one batch, connecting first if needed. Resolves with the server's ack or throws. */
+    async send(events) {
+        this.clearIdleTimer();
+        try {
+            await this.ensureConnected();
+            return await this.emit(events);
+        }
+        finally {
+            this.scheduleIdleDisconnect();
+        }
+    }
+    destroy() {
+        this.clearIdleTimer();
+        this.socket?.removeAllListeners();
+        this.socket?.disconnect();
+        this.socket = null;
+    }
+    ensureConnected() {
+        if (this.socket?.connected)
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        if (!this.socket) {
+            this.socket = this.createSocket();
+        }
+        else if (!this.socket.active) {
+            // Cleanly disconnected earlier (our own idle timeout, or the server closed
+            // it): socket.io-client won't retry on its own, so ask it to.
+            this.socket.connect();
+        }
+        // Otherwise the existing socket is already reconnecting on its own; just wait below.
+        const socket = this.socket;
+        this.connecting = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new TransportError(`connection not established within ${this.options.connectTimeoutMs}ms`, "ECONNECT_TIMEOUT"));
+            }, this.options.connectTimeoutMs);
+            const onConnect = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(classifyConnectError(err));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                socket.off("connect", onConnect);
+                socket.off("connect_error", onError);
+            };
+            socket.once("connect", onConnect);
+            socket.once("connect_error", onError);
+        }).finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    createSocket() {
+        const socket = (0, socket_io_client_1.io)(`${this.origin.origin}${INGEST_NAMESPACE}`, {
+            auth: { apiKey: this.options.apiKey },
+            transports: ["websocket"],
+            reconnection: true,
+            reconnectionAttempts: Infinity,
+            reconnectionDelay: this.options.reconnectionDelayMs,
+            reconnectionDelayMax: this.options.reconnectionDelayMaxMs,
+            randomizationFactor: 0.5,
+            timeout: this.options.connectTimeoutMs,
+            // Never the reason the process stays alive — same property the old HTTP
+            // transport's unref'd keep-alive sockets had.
+            autoUnref: true,
+            forceNew: true,
+            ca: this.options.ca,
+            extraHeaders: { "user-agent": this.options.userAgent },
+        });
+        return socket;
+    }
+    emit(events) {
+        const socket = this.socket;
+        if (!socket) {
+            return Promise.reject(new TransportError("not connected", "ENOTCONNECTED"));
+        }
+        return new Promise((resolve, reject) => {
+            socket.timeout(this.options.timeoutMs).emit(INGEST_EVENT, { events }, (err, ack) => {
+                if (err) {
+                    reject(new TransportError(`no response within ${this.options.timeoutMs}ms`, "ETIMEDOUT"));
+                }
+                else {
+                    resolve(ack);
+                }
+            });
+        });
+    }
+    scheduleIdleDisconnect() {
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            this.socket?.disconnect();
+        }, this.options.idleDisconnectMs);
+        this.idleTimer.unref?.();
+    }
+    clearIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+}
+exports.SocketTransport = SocketTransport;
+/**
+ * `connect_error` from a plain `io()` connect-timeout has message "timeout" and
+ * no further detail. Anything else wraps the real Node error (ECONNREFUSED,
+ * ENOTFOUND, a TLS failure, ...) inside engine.io-client's TransportError, whose
+ * `.description` — for the websocket transport — is a `ws` ErrorEvent exposing
+ * the underlying error via its public `.error` getter (mirrors the DOM
+ * ErrorEvent.error field; see ws/lib/event-target.js). Verified empirically
+ * against the installed socket.io-client/ws versions, not assumed.
+ */
+function classifyConnectError(err) {
+    const anyErr = err;
+    if (anyErr?.message === "timeout") {
+        return new TransportError("connection timed out", "ECONNECT_TIMEOUT");
+    }
+    const inner = anyErr?.description?.error;
+    const code = inner?.code ?? "";
+    const message = inner?.message ?? anyErr?.message ?? "connection failed";
+    return new TransportError(message, code);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "midline-agent",
-  "version": "0.4.0",
-  "description": "Midline — request, error and security monitoring for Node, and error, network and Web Vitals monitoring for browsers",
+  "version": "0.5.0",
+  "description": "Midline — request, error and security monitoring for Node, and error, network, Web Vitals and pageview/visitor monitoring for browsers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -55,9 +55,13 @@
     "@types/express": "^4.17.19",
     "@types/node": "^24.10.1",
     "express": "^4.18.2",
+    "socket.io": "^4.8.3",
     "typescript": "^5.1.3"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
   }
 }

package/src/agent.ts

@@ -2,7 +2,7 @@ import { ConfigError, ResolvedCapture, ResolvedConfig, envFlag, resolveConfig }
 import { ConsoleCapture, ConsoleLevel, ConsoleLine, MAX_LINE_CHARS, withoutConsoleCapture } from "./console";
 import type { RequestContext } from "./context";
 import { Redactor } from "./redact";
-import { Transport } from "./transport";
+import { IngestAck, SocketTransport } from "./socket-transport";
 import { CapturedMessage, EventCategory, EventSeverity, MidlineConfig, MidlineEvent } from "./types";
 
 export const SDK_VERSION: string = (() => {
@@ -117,7 +117,7 @@ export class MidlineAgent {
 
   private readonly config: ResolvedConfig | null = null;
   private readonly redactor: Redactor;
-  private readonly transport: Transport | null = null;
+  private readonly transport: SocketTransport | null = null;
   private readonly onErrorHook?: (message: string) => void;
   private readonly debugLogs: boolean;
 
@@ -165,16 +165,20 @@ export class MidlineAgent {
     }
 
     this.config = resolved;
-    this.transport = new Transport(resolved.ingestUrl, {
+    this.transport = new SocketTransport(resolved.socketOrigin, {
+      apiKey: resolved.apiKey,
       ca: resolved.ca,
       connectTimeoutMs: resolved.connectTimeoutMs,
       timeoutMs: resolved.timeoutMs,
+      reconnectionDelayMs: resolved.flushIntervalMs,
+      reconnectionDelayMaxMs: resolved.maxRetryDelayMs,
+      idleDisconnectMs: Math.max(5 * resolved.flushIntervalMs, 30_000),
       userAgent: `midline-agent/${SDK_VERSION} node/${process.version}`,
     });
 
     this.timer = setInterval(() => {
       this.consoleCapture?.flushPending();
-      void this.drain(false);
+      void this.drain();
     }, resolved.flushIntervalMs);
     // Telemetry must never be the reason a process refuses to exit.
     this.timer.unref?.();
@@ -288,7 +292,15 @@ export class MidlineAgent {
     return true;
   }
 
-  /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
+  /**
+   * Sends whatever is buffered now, ignoring backoff.
+   *
+   * The transport's connection is always unref'd (telemetry alone must never
+   * keep an otherwise-idle process alive), so this relies on something else in
+   * the process keeping the event loop open until the await resolves — true for
+   * the overwhelmingly common case (a running server), not guaranteed for a
+   * bare script whose last statement is `await agent.flush()`.
+   */
   async flush(): Promise<void> {
     if (!this.active) return;
     this.consoleCapture?.flushPending(true);
@@ -296,7 +308,7 @@ export class MidlineAgent {
     if (this.drainPromise) {
       await this.drainPromise;
     }
-    await this.drain(true);
+    await this.drain();
   }
 
   /** Flushes with a deadline, then closes. For graceful shutdown. */
@@ -493,23 +505,23 @@ export class MidlineAgent {
     return batch;
   }
 
-  private drain(keepProcessAlive: boolean): Promise<void> {
+  private drain(): Promise<void> {
     if (this.drainPromise) return this.drainPromise;
     if (!this.active || !this.queue.length || Date.now() < this.retryAfter) {
       return Promise.resolve();
     }
-    this.drainPromise = this.runDrain(keepProcessAlive).finally(() => {
+    this.drainPromise = this.runDrain().finally(() => {
       this.drainPromise = null;
     });
     return this.drainPromise;
   }
 
-  private async runDrain(keepProcessAlive: boolean): Promise<void> {
+  private async runDrain(): Promise<void> {
     while (this.queue.length && this.active) {
       // Taken off the queue while in flight, so overflow trimming can't remove
       // events that are mid-send and then be confused about what was accepted.
       const batch = this.takeBatch();
-      const outcome = await this.send(batch, keepProcessAlive);
+      const outcome = await this.send(batch);
 
       if (outcome.kind === "ok") {
         this.onSuccess();
@@ -530,7 +542,7 @@ export class MidlineAgent {
           this.requeue(batch);
         } else {
           this.dropped += 1;
-          this.report("http-413", "midline: the Midline server rejected an event as too large (HTTP 413); dropped it.");
+          this.report("too-large", "midline: the Midline server rejected an event as too large; dropped it.");
         }
         continue;
       }
@@ -543,7 +555,7 @@ export class MidlineAgent {
         }
         // One malformed event fails validation for the whole batch. Send them one
         // at a time so it only costs that event.
-        const isolated = await this.sendIndividually(batch, keepProcessAlive);
+        const isolated = await this.sendIndividually(batch);
         if (!isolated) return;
         continue;
       }
@@ -555,14 +567,14 @@ export class MidlineAgent {
   }
 
   /** Returns false if delivery should stop for this drain. */
-  private async sendIndividually(batch: QueuedEvent[], keepProcessAlive: boolean): Promise<boolean> {
+  private async sendIndividually(batch: QueuedEvent[]): Promise<boolean> {
     for (let index = 0; index < batch.length; index++) {
       if (this.consoleUnsupported && batch[index].wire.eventType === "console") continue;
-      const outcome = await this.send([batch[index]], keepProcessAlive);
+      const outcome = await this.send([batch[index]]);
       if (outcome.kind === "ok") {
         this.onSuccess();
       } else if (outcome.kind === "rejected" || outcome.kind === "tooLarge") {
-        const detail = outcome.kind === "rejected" ? outcome.detail : "HTTP 413";
+        const detail = outcome.kind === "rejected" ? outcome.detail : "too_large";
         if (outcome.kind === "rejected" && this.refusedConsole(batch[index], detail)) continue;
         this.dropped += 1;
         this.report(`rejected:${detail}`, `midline: the Midline server rejected an event (${detail}); dropped it.`);
@@ -578,60 +590,44 @@ export class MidlineAgent {
     return true;
   }
 
-  private async send(batch: QueuedEvent[], keepProcessAlive: boolean): Promise<Outcome> {
-    const config = this.config!;
-    const body = JSON.stringify({ events: batch.map((item) => item.wire) });
-
-    let result;
+  private async send(batch: QueuedEvent[]): Promise<Outcome> {
+    let ack: IngestAck;
     try {
-      result = await this.transport!.post(config.batchUrl, body, { "x-api-key": config.apiKey }, keepProcessAlive);
+      ack = await this.transport!.send(batch.map((item) => item.wire));
     } catch (err) {
       this.report(`transport:${errorCode(err)}`, this.describe(err, batch.length));
       return { kind: "retry" };
     }
 
-    const { status } = result;
-    if (status >= 200 && status < 300) {
-      // Servers that predate 401-on-bad-key answer 201 and count the rejects.
-      const summary = parseJson(result.body);
-      const failed = typeof summary?.failed === "number" ? summary.failed : 0;
-      if (failed >= batch.length && batch.length > 0) {
+    if (ack.ok) {
+      // Servers that predate 401-on-bad-key ack ok and count the rejects.
+      if (ack.rejected >= batch.length && batch.length > 0) {
         this.log("error", "midline: the Midline server did not accept this API key. Monitoring is now off — retrying wouldn't help. Check apiKey / MIDLINE_API_KEY.");
         return { kind: "stop" };
       }
-      if (failed > 0) {
-        this.dropped += failed;
-        this.report("partial", `midline: the Midline server rejected ${failed} of ${batch.length} events.`);
+      if (ack.rejected > 0) {
+        this.dropped += ack.rejected;
+        this.report("partial", `midline: the Midline server rejected ${ack.rejected} of ${batch.length} events.`);
       }
       return { kind: "ok" };
     }
-    if (status === 401 || status === 403) {
+
+    if (ack.code === "unauthorized" || ack.code === "forbidden") {
       this.log(
         "error",
-        `midline: the Midline server rejected the API key (HTTP ${status}). ` +
+        `midline: the Midline server rejected the API key (${ack.code}). ` +
           "Monitoring is now off — retrying wouldn't help. Check apiKey / MIDLINE_API_KEY.",
       );
       return { kind: "stop" };
     }
-    if (status === 413) {
+    if (ack.code === "too_large") {
       return { kind: "tooLarge" };
     }
-    if (status === 408 || status === 429 || status >= 500) {
-      const retryAfterMs = parseRetryAfter(result.headers["retry-after"]);
-      this.report(`http-${status}`, `midline: the Midline server returned HTTP ${status}; events are buffered and will be retried.`);
-      return { kind: "retry", retryAfterMs };
-    }
-    if (status >= 300 && status < 400) {
-      // Never followed: that would hand the API key to wherever the redirect points.
-      const location = String(result.headers.location ?? "").slice(0, 200);
-      this.report(
-        `http-${status}`,
-        `midline: the Midline endpoint redirected (HTTP ${status}${location ? ` to ${location}` : ""}). ` +
-          "Redirects are not followed; set MIDLINE_ENDPOINT to the final URL.",
-      );
-      return { kind: "retry" };
+    if (ack.code === "rate_limited") {
+      this.report("rate_limited", `midline: the Midline server is rate-limiting this project; events are buffered and will be retried.`);
+      return { kind: "retry", retryAfterMs: ack.retryAfterMs };
     }
-    return { kind: "rejected", detail: `HTTP ${status}${serverMessage(result.body)}` };
+    return { kind: "rejected", detail: `${ack.code}: ${ack.message}` };
   }
 
   /**
@@ -666,7 +662,7 @@ export class MidlineAgent {
 
   private describe(err: unknown, inFlight: number): string {
     const config = this.config!;
-    const origin = config.ingestUrl.origin;
+    const origin = config.socketOrigin.origin;
     const code = errorCode(err);
     const buffered = ` ${this.queue.length + inFlight} event(s) buffered; your application is unaffected.`;
 
@@ -687,7 +683,7 @@ export class MidlineAgent {
       return `midline: could not connect to ${origin} within ${config.connectTimeoutMs}ms; retrying with backoff.${buffered}`;
     }
     if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
-      return `midline: cannot resolve ${config.ingestUrl.hostname} (${code}) — check MIDLINE_ENDPOINT and DNS; retrying with backoff.${buffered}`;
+      return `midline: cannot resolve ${config.socketOrigin.hostname} (${code}) — check MIDLINE_ENDPOINT and DNS; retrying with backoff.${buffered}`;
     }
     if (code === "ECONNREFUSED") {
       return `midline: ${origin} refused the connection; retrying with backoff.${buffered}`;
@@ -828,26 +824,3 @@ function errorCode(err: unknown): string {
   const e = err as any;
   return String(e?.code ?? e?.cause?.code ?? e?.errno ?? e?.name ?? "");
 }
-
-function parseJson(text: string): any {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return undefined;
-  }
-}
-
-function serverMessage(body: string): string {
-  const message = parseJson(body)?.message;
-  const text = Array.isArray(message) ? message.join("; ") : typeof message === "string" ? message : "";
-  return text ? `: ${text.slice(0, 300)}` : "";
-}
-
-function parseRetryAfter(header: string | string[] | undefined): number | undefined {
-  const value = Array.isArray(header) ? header[0] : header;
-  if (!value) return undefined;
-  const seconds = Number(value);
-  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
-  const date = Date.parse(value);
-  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
-}

package/src/browser/client.ts

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

package/src/browser/types.ts

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

package/src/browser/version.ts

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

package/src/config.ts

@@ -4,7 +4,6 @@ import * as tls from "tls";
 import { CaInput, CaptureOptions, MidlineConfig } from "./types";
 
 export const DEFAULT_ENDPOINT = "https://api.usemidline.com";
-export const INGEST_PATH = "/api/api-monitor/events";
 
 /** A setting that cannot work as given. Thrown at construction, never while serving traffic. */
 export class ConfigError extends Error {
@@ -25,8 +24,8 @@ export interface ResolvedCapture {
 export interface ResolvedConfig {
   apiKey: string;
   serviceName?: string;
-  ingestUrl: URL;
-  batchUrl: URL;
+  /** The Midline server's origin; the ingest gateway lives at `${socketOrigin}/ingest`. */
+  socketOrigin: URL;
   /** Full trust store for the Midline endpoint, or undefined for Node's default. */
   ca?: Array<string | Buffer>;
   hasCustomCa: boolean;
@@ -83,12 +82,14 @@ export function isLoopback(hostname: string): boolean {
 }
 
 /**
- * Turns whatever the user configured into the ingest URL.
- *
+ * Turns whatever the user configured into the Midline server's origin — the
+ * agent connects to `${origin}/ingest` over socket.io, so only the origin
+ * matters now. Tolerates an old-style full ingest URL some existing
+ * `MIDLINE_ENDPOINT` values still carry (from before the socket.io transport):
  * `https://api.usemidline.com`, `https://api.usemidline.com/api/api-monitor/events`
- * and `https://gateway.internal/midline` all work; the last is treated as a prefix.
+ * and `https://gateway.internal/midline` all resolve to the same origin.
  */
-export function resolveIngestUrl(endpoint: string): URL {
+export function resolveEndpointOrigin(endpoint: string): URL {
   let url: URL;
   try {
     url = new URL(endpoint);
@@ -109,18 +110,7 @@ export function resolveIngestUrl(endpoint: string): URL {
     throw new ConfigError("endpoint must not contain credentials; pass the key as apiKey");
   }
 
-  url.search = "";
-  url.hash = "";
-
-  const path = url.pathname.replace(/\/+$/, "");
-  if (path.endsWith(`${INGEST_PATH}/batch`)) {
-    url.pathname = path.slice(0, -"/batch".length);
-  } else if (path.endsWith(INGEST_PATH)) {
-    url.pathname = path;
-  } else {
-    url.pathname = `${path}${INGEST_PATH}`;
-  }
-  return url;
+  return new URL(url.origin);
 }
 
 /**
@@ -198,18 +188,17 @@ export function resolveCapture(capture: CaptureOptions | undefined): ResolvedCap
 
 export function resolveConfig(config: MidlineConfig): ResolvedConfig {
   const apiKey = (config.apiKey ?? env("MIDLINE_API_KEY") ?? "").trim();
-  const ingestUrl = resolveIngestUrl(config.endpoint || env("MIDLINE_ENDPOINT") || DEFAULT_ENDPOINT);
+  const socketOrigin = resolveEndpointOrigin(config.endpoint || env("MIDLINE_ENDPOINT") || DEFAULT_ENDPOINT);
   const extraCa = loadCa(config.ca ?? env("MIDLINE_CUSTOM_CA"), "ca / MIDLINE_CUSTOM_CA");
 
-  if (extraCa && ingestUrl.protocol !== "https:") {
+  if (extraCa && socketOrigin.protocol !== "https:") {
     throw new ConfigError("ca / MIDLINE_CUSTOM_CA is set but the endpoint is not https://");
   }
 
   return {
     apiKey,
     serviceName: config.serviceName ?? env("MIDLINE_SERVICE_NAME"),
-    ingestUrl,
-    batchUrl: new URL(`${ingestUrl.pathname}/batch`, ingestUrl),
+    socketOrigin,
     ca: trustStore(extraCa),
     hasCustomCa: Boolean(extraCa),
     environment: config.environment ?? env("MIDLINE_ENVIRONMENT"),