midline-agent 0.3.0 → 0.4.0

package/src/browser/vitals.ts

@@ -0,0 +1,149 @@
+export type VitalName = "LCP" | "INP" | "CLS" | "FCP" | "TTFB";
+export type VitalRating = "good" | "needs-improvement" | "poor";
+
+export interface VitalsReport {
+  vitals: Partial<Record<VitalName, { value: number; rating: VitalRating }>>;
+  navigationType?: string;
+}
+
+/** web.dev thresholds: at or under the first is good, over the second is poor. */
+const THRESHOLDS: Record<VitalName, [number, number]> = {
+  LCP: [2500, 4000],
+  INP: [200, 500],
+  CLS: [0.1, 0.25],
+  FCP: [1800, 3000],
+  TTFB: [800, 1800],
+};
+
+const rate = (name: VitalName, value: number): VitalRating =>
+  value <= THRESHOLDS[name][0] ? "good" : value <= THRESHOLDS[name][1] ? "needs-improvement" : "poor";
+
+type Entry = PerformanceEntry & {
+  value?: number;
+  hadRecentInput?: boolean;
+  interactionId?: number;
+  activationStart?: number;
+  responseStart?: number;
+  type?: string;
+};
+
+/**
+ * Core Web Vitals without a dependency, measured the way the web-vitals library
+ * does and reported once, when the page is first hidden (the last moment a
+ * report reliably gets out). Browsers that don't expose an entry type simply
+ * omit that metric: Safari has no LCP, INP or CLS.
+ */
+export function observeVitals(win: Window, onReport: (report: VitalsReport) => void): () => void {
+  const Observer = (win as Window & { PerformanceObserver?: typeof PerformanceObserver }).PerformanceObserver;
+  const supported: readonly string[] = Observer?.supportedEntryTypes ?? [];
+  const perf = win.performance;
+  const doc = win.document;
+
+  const values: Partial<Record<VitalName, number>> = {};
+  const observers: Array<{ observer: PerformanceObserver; handle: (entries: Entry[]) => void }> = [];
+
+  let activationStart = 0;
+  let navigationType: string | undefined;
+  try {
+    const navigation = perf?.getEntriesByType?.("navigation")?.[0] as Entry | undefined;
+    if (navigation) {
+      activationStart = navigation.activationStart ?? 0;
+      navigationType = navigation.type;
+      if (typeof navigation.responseStart === "number" && navigation.responseStart > 0) {
+        values.TTFB = Math.max(0, navigation.responseStart - activationStart);
+      }
+    }
+  } catch {
+    // no navigation timing
+  }
+
+  const observe = (type: string, handle: (entries: Entry[]) => void, extra: Record<string, unknown> = {}) => {
+    if (!Observer || !supported.includes(type)) return;
+    try {
+      const observer = new Observer((list) => handle(list.getEntries() as Entry[]));
+      observer.observe({ type, buffered: true, ...extra } as PerformanceObserverInit);
+      observers.push({ observer, handle });
+    } catch {
+      // unsupported option in this browser
+    }
+  };
+
+  observe("paint", (entries) => {
+    for (const entry of entries) {
+      if (entry.name === "first-contentful-paint") values.FCP = Math.max(0, entry.startTime - activationStart);
+    }
+  });
+
+  observe("largest-contentful-paint", (entries) => {
+    const last = entries[entries.length - 1];
+    if (last) values.LCP = Math.max(0, last.startTime - activationStart);
+  });
+
+  // CLS is the largest session window: shifts less than 1s apart, at most 5s long.
+  let windowValue = 0;
+  let windowStart = 0;
+  let windowLast = 0;
+  observe("layout-shift", (entries) => {
+    for (const entry of entries) {
+      if (entry.hadRecentInput || typeof entry.value !== "number") continue;
+      if (windowValue && entry.startTime - windowLast < 1000 && entry.startTime - windowStart < 5000) {
+        windowValue += entry.value;
+      } else {
+        windowValue = entry.value;
+        windowStart = entry.startTime;
+      }
+      windowLast = entry.startTime;
+      values.CLS = Math.max(values.CLS ?? 0, windowValue);
+    }
+  });
+
+  // INP: the slowest interaction, or near the 98th percentile on busy pages.
+  const interactions = new Map<number, number>();
+  const recordInteractions = (entries: Entry[]) => {
+    for (const entry of entries) {
+      if (!entry.interactionId) continue;
+      interactions.set(entry.interactionId, Math.max(interactions.get(entry.interactionId) ?? 0, entry.duration));
+    }
+  };
+  observe("event", recordInteractions, { durationThreshold: 40 });
+  observe("first-input", recordInteractions);
+
+  let reported = false;
+  const report = () => {
+    if (reported) return;
+    reported = true;
+    for (const { observer, handle } of observers) {
+      try {
+        handle(observer.takeRecords() as Entry[]);
+        observer.disconnect();
+      } catch {
+        // already disconnected
+      }
+    }
+    if (interactions.size) {
+      const durations = [...interactions.values()].sort((a, b) => b - a);
+      values.INP = durations[Math.min(durations.length - 1, Math.floor(durations.length / 50))];
+    }
+
+    const vitals: VitalsReport["vitals"] = {};
+    for (const name of Object.keys(values) as VitalName[]) {
+      const raw = values[name];
+      if (typeof raw !== "number" || !Number.isFinite(raw)) continue;
+      const value = name === "CLS" ? Math.round(raw * 10_000) / 10_000 : Math.round(raw);
+      vitals[name] = { value, rating: rate(name, value) };
+    }
+    if (Object.keys(vitals).length) onReport({ vitals, navigationType });
+  };
+
+  const onVisibility = () => {
+    if (doc?.visibilityState === "hidden") report();
+  };
+  doc?.addEventListener("visibilitychange", onVisibility, true);
+  win.addEventListener("pagehide", report, true);
+
+  return () => {
+    doc?.removeEventListener("visibilitychange", onVisibility, true);
+    win.removeEventListener("pagehide", report, true);
+    for (const { observer } of observers) observer.disconnect();
+  };
+}

package/src/redact.ts

@@ -1,4 +1,7 @@
 /**
+ * Shared by the Node agent and the browser SDK, so nothing here may touch a
+ * Node-only global (Buffer, process) — TextEncoder and URLSearchParams exist in both.
+ *
  * Redaction happens in the host process, before an event is queued. Whatever is
  * removed here never reaches a socket, a log line or the Midline server.
  *
@@ -124,7 +127,8 @@ export class Redactor {
     if (typeof input === "bigint") return input.toString();
     if (typeof input === "function" || typeof input === "symbol") return undefined;
     if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input.toISOString();
-    if (Buffer.isBuffer(input) || ArrayBuffer.isView(input)) {
+    // Buffer is a Uint8Array, so this also covers it without naming a Node-only global.
+    if (ArrayBuffer.isView(input)) {
       return `[Binary ${(input as ArrayBufferView).byteLength} bytes]`;
     }
     if (typeof input !== "object") return undefined;
@@ -190,11 +194,13 @@ export class Redactor {
 
     const type = (contentType || "").toLowerCase();
 
-    if (typeof raw === "object" && !Buffer.isBuffer(raw)) {
+    if (typeof raw === "object" && !ArrayBuffer.isView(raw)) {
       return this.fit(this.value(raw), maxBytes);
     }
 
-    const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+    const text = ArrayBuffer.isView(raw)
+      ? new TextDecoder().decode(raw as ArrayBufferView)
+      : String(raw);
 
     if (type.includes("json")) {
       try {
@@ -214,18 +220,18 @@ export class Redactor {
 
   private fit(value: unknown, maxBytes: number): { body?: unknown; truncated?: boolean } {
     const serialized = JSON.stringify(value) ?? "";
-    if (Buffer.byteLength(serialized) <= maxBytes) {
+    if (new TextEncoder().encode(serialized).length <= maxBytes) {
       return { body: value };
     }
     return this.cut(serialized, maxBytes);
   }
 
   private cut(text: string, maxBytes: number): { body?: unknown; truncated?: boolean } {
-    const bytes = Buffer.from(text);
+    const bytes = new TextEncoder().encode(text);
     if (bytes.length <= maxBytes) {
       return { body: text };
     }
     // Slicing bytes can split a multi-byte character; the replacement char is harmless here.
-    return { body: bytes.subarray(0, maxBytes).toString("utf8"), truncated: true };
+    return { body: new TextDecoder().decode(bytes.subarray(0, maxBytes)), truncated: true };
   }
 }

package/test/browser.test.js

@@ -0,0 +1,328 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const Midline = require("../dist/browser");
+const { BROWSER_SDK_VERSION, resolveBatchUrl } = Midline;
+
+const PAGE = "https://app.example.com/checkout";
+const INGEST = "https://api.usemidline.com/api/api-monitor/events/batch";
+const KEY = "pk_0123456789abcdef";
+
+/**
+ * A window made of Node's own web globals (EventTarget, fetch types, performance),
+ * with a fetch that answers from a table instead of the network.
+ */
+function fakeWindow({ ingestStatus = 201, ingestBody = '{"success":1}' } = {}) {
+  const win = new EventTarget();
+  const location = new URL(PAGE);
+  const calls = [];
+  const warnings = [];
+
+  Object.assign(win, {
+    location: {
+      get href() { return location.href; },
+      get origin() { return location.origin; },
+      get pathname() { return location.pathname; },
+      get hash() { return location.hash; },
+      get search() { return location.search; },
+    },
+    document: Object.assign(new EventTarget(), { visibilityState: "visible" }),
+    navigator: { userAgent: "node-test" },
+    console: {
+      warn: (...args) => warnings.push(args.join(" ")),
+      log: () => {},
+      error: () => {},
+      info: () => {},
+      debug: () => {},
+    },
+    history: {
+      pushState(_state, _title, url) { location.href = new URL(url, location.href).href; },
+      replaceState(_state, _title, url) { location.href = new URL(url, location.href).href; },
+    },
+    performance,
+  });
+
+  win.fetch = async (input, init) => {
+    const url = String(input instanceof Request ? input.url : input);
+    calls.push({ url, init });
+    if (url === INGEST) return new Response(ingestBody, { status: ingestStatus });
+    if (url.endsWith("/offline")) throw new TypeError("Failed to fetch");
+    if (url.endsWith("/aborted")) throw Object.assign(new Error("aborted"), { name: "AbortError" });
+    const status = Number(new URL(url, PAGE).searchParams.get("status") || 200);
+    return new Response(status === 204 ? null : "{}", { status });
+  };
+
+  globalThis.window = win;
+  return {
+    win,
+    calls,
+    warnings,
+    sent: () =>
+      calls
+        .filter((call) => call.url === INGEST)
+        .flatMap((call) => JSON.parse(call.init.body).events),
+  };
+}
+
+function uncaught(win, error, extra = {}) {
+  const event = new Event("error");
+  for (const [key, value] of Object.entries({ error, message: error?.message, ...extra })) {
+    Object.defineProperty(event, key, { value });
+  }
+  win.dispatchEvent(event);
+}
+
+async function withSdk(config, run, windowOptions) {
+  const env = fakeWindow(windowOptions);
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, ...config });
+  try {
+    await run(env);
+  } finally {
+    await Midline.close();
+    delete globalThis.window;
+  }
+}
+
+test("browser: the version constant matches package.json", () => {
+  assert.equal(BROWSER_SDK_VERSION, require("../package.json").version);
+});
+
+test("browser: endpoint accepts a base or ingest URL, https only except localhost", () => {
+  assert.equal(resolveBatchUrl(), INGEST);
+  assert.equal(resolveBatchUrl("https://midline.internal/"), "https://midline.internal/api/api-monitor/events/batch");
+  assert.equal(resolveBatchUrl("https://midline.internal/api/api-monitor/events"), "https://midline.internal/api/api-monitor/events/batch");
+  assert.equal(resolveBatchUrl("http://localhost:8076"), "http://localhost:8076/api/api-monitor/events/batch");
+  assert.throws(() => resolveBatchUrl("http://midline.internal"), /https/);
+  assert.throws(() => resolveBatchUrl("https://user:pw@midline.internal"), /credentials/);
+});
+
+test("browser: does nothing without a window, as during server-side rendering", async () => {
+  delete globalThis.window;
+  assert.doesNotThrow(() => Midline.init({ apiKey: KEY }));
+  assert.doesNotThrow(() => Midline.captureException(new Error("ssr")));
+  await Midline.close();
+});
+
+test("browser: refuses a server key and leaves the page untouched", async () => {
+  const env = fakeWindow();
+  const originalFetch = env.win.fetch;
+  Midline.init({ apiKey: "ak_secret_server_key" });
+  assert.equal(env.win.fetch, originalFetch);
+  assert.match(env.warnings.join("\n"), /server key \(ak_/);
+  Midline.captureException(new Error("nope"));
+  await Midline.flush();
+  assert.equal(env.calls.length, 0);
+  await Midline.close();
+  delete globalThis.window;
+});
+
+test("browser: uncaught errors and rejections become redacted error events", async () => {
+  await withSdk({ service: "checkout-web", release: "1.2.3" }, async ({ win, calls, sent }) => {
+    uncaught(win, new TypeError("cannot read password=hunter2 of undefined"), {
+      filename: "https://app.example.com/assets/app.js?token=abc",
+      lineno: 12,
+      colno: 7,
+    });
+    const rejection = new Event("unhandledrejection");
+    Object.defineProperty(rejection, "reason", { value: "plain string reason" });
+    win.dispatchEvent(rejection);
+    await Midline.flush();
+
+    const [error, rejected] = sent();
+    assert.equal(error.eventType, "error");
+    assert.equal(error.route, "/checkout");
+    assert.equal(error.payload.type, "TypeError");
+    assert.equal(error.payload.mechanism, "onerror");
+    assert.equal(error.payload.error, "cannot read password=[REDACTED] of undefined");
+    assert.equal(error.payload.context.filename, "https://app.example.com/assets/app.js");
+    assert.equal(error.service, "checkout-web");
+    assert.equal(error.release, "1.2.3");
+    assert.equal(error.metadata.sdk, "midline-agent/browser");
+    assert.equal(error.metadata.runtime, "browser");
+    assert.match(error.traceId, /^[a-f0-9]{32}$/);
+    assert.equal(error.statusCode, undefined, "a browser error is not an HTTP 500");
+
+    assert.equal(rejected.payload.error, "plain string reason");
+    assert.equal(rejected.payload.mechanism, "unhandledrejection");
+
+    const delivery = calls.find((call) => call.url === INGEST);
+    assert.equal(delivery.init.headers["X-API-Key"], KEY);
+    assert.equal(delivery.init.credentials, "omit");
+    assert.doesNotMatch(delivery.init.body, /hunter2/);
+  });
+});
+
+test("browser: the same error twice in quick succession is sent once; cross-origin 'Script error.' is skipped", async () => {
+  await withSdk({}, async ({ win, sent }) => {
+    const boom = new Error("render loop");
+    uncaught(win, boom);
+    uncaught(win, boom);
+    uncaught(win, undefined, { message: "Script error." });
+    await Midline.flush();
+    assert.equal(sent().length, 1);
+  });
+});
+
+test("browser: fetch gets a traceparent on same-origin calls only, and failures become events", async () => {
+  await withSdk({}, async ({ win, calls, sent }) => {
+    await win.fetch("/api/charges?status=500&card=4242", { method: "post" });
+    await win.fetch("https://third-party.example/pixel?status=200");
+    await win.fetch(new Request("https://app.example.com/api/cart?status=200", { headers: { "x-custom": "kept" } }));
+    await assert.rejects(win.fetch("/api/offline"));
+    await assert.rejects(win.fetch("/api/aborted"));
+    await Midline.flush();
+
+    const sameOrigin = calls.find((call) => call.url.includes("/api/charges"));
+    const traceparent = sameOrigin.init.headers.get("traceparent");
+    assert.match(traceparent, /^00-[a-f0-9]{32}-[a-f0-9]{16}-01$/);
+    assert.equal(calls.find((call) => call.url.includes("third-party")).init, undefined, "cross-origin calls are untouched");
+    const fromRequest = calls.find((call) => call.url.includes("/api/cart"));
+    assert.equal(fromRequest.init.headers.get("x-custom"), "kept", "a Request's own headers survive");
+
+    const events = sent();
+    assert.equal(events.length, 2, "only the 500 and the network failure are events; the 200s and the abort are not");
+    const [failed, offline] = events;
+    assert.equal(failed.eventType, "request");
+    assert.equal(failed.route, "/api/charges");
+    assert.equal(failed.method, "POST");
+    assert.equal(failed.statusCode, 500);
+    assert.equal(failed.severity, "high");
+    assert.equal(failed.traceId, traceparent.split("-")[1]);
+    assert.equal(failed.spanId, traceparent.split("-")[2]);
+    assert.equal(failed.payload.request.query.card, "4242");
+
+    assert.equal(offline.eventType, "error");
+    assert.equal(offline.payload.code, "NETWORK_ERROR");
+    assert.equal(offline.statusCode, undefined);
+    assert.ok(offline.payload.breadcrumbs.some((crumb) => crumb.message === "POST /api/charges 500"));
+
+    assert.ok(!events.some((event) => event.route.includes("api-monitor")), "Midline's own delivery is never recorded");
+  });
+});
+
+test("browser: captureRequests 'all' records successful calls too", async () => {
+  await withSdk({ captureRequests: "all" }, async ({ win, sent }) => {
+    await win.fetch("/api/ok?status=204");
+    await Midline.flush();
+    assert.equal(sent()[0].statusCode, 204);
+    assert.equal(sent()[0].severity, "low");
+  });
+});
+
+test("browser: a refused key switches the SDK off after one warning", async () => {
+  await withSdk(
+    {},
+    async ({ win, warnings, sent, calls }) => {
+      Midline.captureMessage("first");
+      await Midline.flush();
+      assert.match(warnings.join("\n"), /HTTP 403: This browser key isn't allowed from this origin/);
+      assert.equal(sent().length, 1);
+
+      Midline.captureMessage("second");
+      uncaught(win, new Error("after stop"));
+      await Midline.flush();
+      assert.equal(calls.filter((call) => call.url === INGEST).length, 1);
+    },
+    { ingestStatus: 403, ingestBody: JSON.stringify({ message: "This browser key isn't allowed from this origin." }) },
+  );
+});
+
+test("browser: server errors are retried rather than dropped", async () => {
+  await withSdk(
+    {},
+    async ({ calls }) => {
+      Midline.captureMessage("kept");
+      await Midline.flush();
+      assert.equal(calls.filter((call) => call.url === INGEST).length, 1);
+      // Backing off: an immediate second flush does not hammer the server.
+      await Midline.flush();
+      assert.equal(calls.filter((call) => call.url === INGEST).length, 1);
+    },
+    { ingestStatus: 503, ingestBody: "" },
+  );
+});
+
+test("browser: beforeSend can drop events and can't add fields the server would reject", async () => {
+  await withSdk(
+    {
+      beforeSend(event) {
+        if (event.payload?.message === "drop me") return null;
+        return { ...event, organisationId: "someone-else", payload: { ...event.payload, extra: "ok" } };
+      },
+    },
+    async ({ sent }) => {
+      Midline.captureMessage("drop me");
+      Midline.captureMessage("keep me", "medium");
+      await Midline.flush();
+      const events = sent();
+      assert.equal(events.length, 1);
+      assert.equal(events[0].organisationId, undefined);
+      assert.equal(events[0].payload.extra, "ok");
+      assert.equal(events[0].severity, "medium");
+    },
+  );
+});
+
+test("browser: user, tags and a rate limit", async () => {
+  await withSdk({ maxEventsPerMinute: 2 }, async ({ sent }) => {
+    Midline.setUser({ id: 42, email: "not kept" });
+    Midline.setTag("plan", "pro");
+    for (let i = 0; i < 5; i++) Midline.captureMessage(`message ${i}`);
+    await Midline.flush();
+    const events = sent();
+    assert.equal(events.length, 2);
+    assert.deepEqual(events[0].metadata.user, { id: "42" });
+    assert.deepEqual(events[0].metadata.tags, { plan: "pro" });
+  });
+});
+
+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 });
+    win.console.info("not captured");
+    await Midline.flush();
+    const [line] = sent();
+    assert.equal(sent().length, 1);
+    assert.equal(line.eventType, "console");
+    assert.equal(line.severity, "high");
+    assert.equal(line.metadata.level, "error");
+    assert.doesNotMatch(line.payload.message, /secret-token/);
+  });
+});
+
+test("browser: navigation starts a new trace; close restores everything it wrapped", async () => {
+  const env = fakeWindow();
+  const { win } = env;
+  const originalFetch = win.fetch;
+  const originalPush = win.history.pushState;
+  const originalError = win.console.error;
+
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, captureConsole: true });
+  assert.notEqual(win.fetch, originalFetch);
+
+  Midline.captureMessage("before");
+  win.history.pushState({}, "", "/orders/7");
+  Midline.captureMessage("after");
+  await Midline.flush();
+  const [before, after] = env.sent();
+  assert.equal(after.route, "/orders/7");
+  assert.notEqual(before.traceId, after.traceId);
+
+  await Midline.close();
+  assert.equal(win.fetch, originalFetch);
+  assert.equal(win.history.pushState, originalPush);
+  assert.equal(win.console.error, originalError);
+  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");
+    win.document.visibilityState = "hidden";
+    win.document.dispatchEvent(new Event("visibilitychange"));
+    await new Promise((resolve) => setImmediate(resolve));
+    const delivery = calls.find((call) => call.url === INGEST);
+    assert.equal(delivery.init.keepalive, true);
+  });
+});

package/tsconfig.esm.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "outDir": "dist/esm",
+    "declaration": false
+  },
+  "include": [
+    "src/browser",
+    "src/redact.ts",
+    "src/types.ts"
+  ]
+}