midline-agent 0.2.0 → 0.4.0

package/dist/browser/index.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROWSER_SDK_VERSION = exports.resolveBatchUrl = exports.Midline = void 0;
+exports.init = init;
+exports.captureException = captureException;
+exports.captureMessage = captureMessage;
+exports.setUser = setUser;
+exports.setTag = setTag;
+exports.addBreadcrumb = addBreadcrumb;
+exports.flush = flush;
+exports.close = close;
+/**
+ * midline-agent/browser — error, network and Web Vitals monitoring for web apps.
+ *
+ *   import * as Midline from "midline-agent/browser";
+ *   Midline.init({ apiKey: "pk_…", service: "checkout-web" });
+ *
+ * Framework-agnostic: it instruments the page (window errors, fetch, XHR,
+ * history), not React, Vue or Angular, so it works under all of them. Call
+ * `captureException` from a framework's own error hook for errors it swallows.
+ */
+const client_js_1 = require("./client.js");
+let client;
+/**
+ * Starts monitoring. Safe to call during server-side rendering (it does nothing
+ * without a window) and safe to call twice (the first instance is closed).
+ * A bad config logs one console warning and leaves the page untouched.
+ */
+function init(config) {
+    if (client)
+        void client.close();
+    client = client_js_1.BrowserClient.create(config);
+}
+/** Reports an error your code caught, e.g. from a React error boundary. */
+function captureException(error, context) {
+    client?.captureException(error, context);
+}
+function captureMessage(message, severity, context) {
+    client?.captureMessage(message, severity, context);
+}
+/** Attaches a user id to later events. Pass null on sign-out. */
+function setUser(user) {
+    client?.setUser(user);
+}
+function setTag(key, value) {
+    client?.setTag(key, value);
+}
+function addBreadcrumb(message, type) {
+    client?.addBreadcrumb(message, type);
+}
+/** Sends anything queued now. */
+function flush() {
+    return client ? client.flush() : Promise.resolve();
+}
+/** Restores everything the SDK wrapped and sends what's queued. */
+async function close() {
+    const closing = client;
+    client = undefined;
+    await closing?.close();
+}
+exports.Midline = { init, captureException, captureMessage, setUser, setTag, addBreadcrumb, flush, close };
+var client_js_2 = require("./client.js");
+Object.defineProperty(exports, "resolveBatchUrl", { enumerable: true, get: function () { return client_js_2.resolveBatchUrl; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "BROWSER_SDK_VERSION", { enumerable: true, get: function () { return version_js_1.BROWSER_SDK_VERSION; } });

package/dist/browser/instrument.d.ts

@@ -0,0 +1,39 @@
+import type { ConsoleLevel } from "./types.js";
+/** A finished fetch or XHR call. `status` is absent when no response arrived. */
+export interface RequestRecord {
+    kind: "fetch" | "xhr";
+    method: string;
+    url: URL;
+    status?: number;
+    durationMs: number;
+    aborted?: boolean;
+    spanId?: string;
+}
+export interface Propagation {
+    headers: Record<string, string>;
+    spanId: string;
+}
+export interface InstrumentHooks {
+    onError(error: unknown, mechanism: "onerror" | "unhandledrejection", location?: ErrorLocation): void;
+    onRequest(record: RequestRecord): void;
+    onConsole(level: ConsoleLevel, args: unknown[]): void;
+    onNavigation(from: string, to: string): void;
+    /** Headers to add to a request, or undefined to leave it untouched. */
+    propagation(url: URL): Propagation | undefined;
+    /** Midline's own delivery requests, which are never recorded. */
+    isOwnRequest(url: URL): boolean;
+}
+export interface ErrorLocation {
+    message?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+}
+type Teardown = () => void;
+export declare function instrumentErrors(win: Window, hooks: InstrumentHooks): Teardown;
+export declare function instrumentFetch(win: Window, original: typeof fetch, hooks: InstrumentHooks): Teardown;
+export declare function instrumentXhr(win: Window, hooks: InstrumentHooks): Teardown;
+export declare function instrumentConsole(target: Console, levels: ConsoleLevel[], hooks: InstrumentHooks): Teardown;
+/** Single-page-app route changes, for breadcrumbs and to start a fresh trace per view. */
+export declare function instrumentHistory(win: Window, hooks: InstrumentHooks): Teardown;
+export {};

package/dist/browser/instrument.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instrumentErrors = instrumentErrors;
+exports.instrumentFetch = instrumentFetch;
+exports.instrumentXhr = instrumentXhr;
+exports.instrumentConsole = instrumentConsole;
+exports.instrumentHistory = instrumentHistory;
+const noop = () => { };
+/** Instrumentation runs inside the page's own calls; a bug here must never become the page's bug. */
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // swallowed on purpose
+    }
+}
+const now = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+function instrumentErrors(win, hooks) {
+    // Registered in the bubble phase: resource load failures (img, script) don't
+    // bubble to window, so only script errors arrive here.
+    const onError = (event) => safely(() => {
+        const e = event;
+        hooks.onError(e.error ?? e.message, "onerror", {
+            message: e.message,
+            filename: e.filename,
+            lineno: e.lineno,
+            colno: e.colno,
+        });
+    });
+    const onRejection = (event) => safely(() => hooks.onError(event.reason, "unhandledrejection"));
+    win.addEventListener("error", onError);
+    win.addEventListener("unhandledrejection", onRejection);
+    return () => {
+        win.removeEventListener("error", onError);
+        win.removeEventListener("unhandledrejection", onRejection);
+    };
+}
+function instrumentFetch(win, original, hooks) {
+    if (typeof original !== "function")
+        return noop;
+    const RequestCtor = typeof Request === "function" ? Request : undefined;
+    const wrapped = function fetch(input, init) {
+        let url;
+        let method = "GET";
+        let nextInit = init;
+        let spanId;
+        try {
+            const isRequest = RequestCtor !== undefined && input instanceof RequestCtor;
+            url = new URL(isRequest ? input.url : String(input), win.location.href);
+            method = String(init?.method ?? (isRequest ? input.method : "GET")).toUpperCase();
+            if (hooks.isOwnRequest(url)) {
+                url = undefined;
+            }
+            else {
+                const propagation = hooks.propagation(url);
+                if (propagation) {
+                    // fetch(request, init) replaces the request's headers with init's, so
+                    // start from whichever the caller actually supplied.
+                    const headers = new Headers(init?.headers ?? (isRequest ? input.headers : undefined));
+                    for (const [name, value] of Object.entries(propagation.headers)) {
+                        if (!headers.has(name))
+                            headers.set(name, value);
+                    }
+                    nextInit = { ...init, headers };
+                    spanId = propagation.spanId;
+                }
+            }
+        }
+        catch {
+            url = undefined;
+            nextInit = init;
+        }
+        const startedAt = now();
+        const promise = original.call(win, input, nextInit);
+        if (url) {
+            const target = url;
+            promise.then((response) => safely(() => hooks.onRequest({ kind: "fetch", method, url: target, status: response.status || undefined, durationMs: now() - startedAt, spanId })), (error) => safely(() => hooks.onRequest({
+                kind: "fetch",
+                method,
+                url: target,
+                durationMs: now() - startedAt,
+                aborted: error?.name === "AbortError",
+                spanId,
+            })));
+        }
+        return promise;
+    };
+    win.fetch = wrapped;
+    return () => {
+        if (win.fetch === wrapped)
+            win.fetch = original;
+    };
+}
+function instrumentXhr(win, hooks) {
+    const Xhr = win.XMLHttpRequest;
+    if (typeof Xhr !== "function")
+        return noop;
+    const proto = Xhr.prototype;
+    const originalOpen = proto.open;
+    const originalSend = proto.send;
+    const originalSetRequestHeader = proto.setRequestHeader;
+    const states = new WeakMap();
+    const open = function (method, url, ...rest) {
+        safely(() => {
+            states.set(this, {
+                method: String(method || "GET").toUpperCase(),
+                url: new URL(String(url), win.location.href),
+                headerNames: new Set(),
+            });
+        });
+        return originalOpen.apply(this, [method, url, ...rest]);
+    };
+    const setRequestHeader = function (name, value) {
+        safely(() => states.get(this)?.headerNames.add(String(name).toLowerCase()));
+        return originalSetRequestHeader.call(this, name, value);
+    };
+    const send = function (body) {
+        const state = states.get(this);
+        if (state?.url && !hooks.isOwnRequest(state.url)) {
+            const url = state.url;
+            let spanId;
+            safely(() => {
+                const propagation = hooks.propagation(url);
+                if (!propagation)
+                    return;
+                for (const [name, value] of Object.entries(propagation.headers)) {
+                    // setRequestHeader appends, so a caller's own traceparent would become "a, b".
+                    if (!state.headerNames.has(name))
+                        originalSetRequestHeader.call(this, name, value);
+                }
+                spanId = propagation.spanId;
+            });
+            const startedAt = now();
+            let aborted = false;
+            this.addEventListener("abort", () => {
+                aborted = true;
+            });
+            this.addEventListener("loadend", () => safely(() => hooks.onRequest({
+                kind: "xhr",
+                method: state.method,
+                url,
+                status: this.status || undefined,
+                durationMs: now() - startedAt,
+                aborted,
+                spanId,
+            })));
+        }
+        return originalSend.call(this, body);
+    };
+    proto.open = open;
+    proto.setRequestHeader = setRequestHeader;
+    proto.send = send;
+    return () => {
+        if (proto.open === open)
+            proto.open = originalOpen;
+        if (proto.setRequestHeader === setRequestHeader)
+            proto.setRequestHeader = originalSetRequestHeader;
+        if (proto.send === send)
+            proto.send = originalSend;
+    };
+}
+function instrumentConsole(target, levels, hooks) {
+    const restores = [];
+    for (const level of levels) {
+        const original = target[level];
+        if (typeof original !== "function")
+            continue;
+        const wrapped = function (...args) {
+            safely(() => hooks.onConsole(level, args));
+            return original.apply(target, args);
+        };
+        target[level] = wrapped;
+        restores.push(() => {
+            if (target[level] === wrapped)
+                target[level] = original;
+        });
+    }
+    return () => restores.forEach((restore) => restore());
+}
+/** Single-page-app route changes, for breadcrumbs and to start a fresh trace per view. */
+function instrumentHistory(win, hooks) {
+    const history = win.history;
+    if (!history || typeof history.pushState !== "function")
+        return noop;
+    let last = win.location.href;
+    const changed = () => safely(() => {
+        const next = win.location.href;
+        if (next === last)
+            return;
+        const previous = last;
+        last = next;
+        hooks.onNavigation(previous, next);
+    });
+    const originalPush = history.pushState;
+    const originalReplace = history.replaceState;
+    const push = function (...args) {
+        const result = originalPush.apply(this, args);
+        changed();
+        return result;
+    };
+    const replace = function (...args) {
+        const result = originalReplace.apply(this, args);
+        changed();
+        return result;
+    };
+    history.pushState = push;
+    history.replaceState = replace;
+    win.addEventListener("popstate", changed);
+    return () => {
+        if (history.pushState === push)
+            history.pushState = originalPush;
+        if (history.replaceState === replace)
+            history.replaceState = originalReplace;
+        win.removeEventListener("popstate", changed);
+    };
+}

package/dist/browser/transport.d.ts

@@ -0,0 +1,43 @@
+import type { BrowserEvent } from "./types.js";
+export interface TransportOptions {
+    batchUrl: string;
+    apiKey: string;
+    /** The page's fetch as it was before instrumentation, so delivery is never recorded as traffic. */
+    fetch: typeof fetch;
+    flushIntervalMs: number;
+    maxBatchSize: number;
+    maxQueueSize: number;
+    debug: (message: string) => void;
+    /** Called once when the server refuses the key; retrying could not help. */
+    onStop: (message: string) => void;
+}
+/**
+ * Batches events and posts them to the ingest API. It never throws into the page
+ * and never blocks it: a Midline outage costs queued telemetry, not the app.
+ */
+export declare class BrowserTransport {
+    private readonly options;
+    private queue;
+    private timer;
+    private sending;
+    private stopped;
+    private retryAt;
+    private backoffMs;
+    dropped: number;
+    constructor(options: TransportOptions);
+    start(): void;
+    enqueue(event: BrowserEvent): void;
+    get size(): number;
+    /** Sends everything queued, one batch at a time, unless Midline asked us to back off. */
+    flush(): Promise<void>;
+    /**
+     * The page is being hidden and may never come back. Hands whatever is queued to
+     * keepalive requests without waiting on them; an in-flight regular flush is left
+     * alone, since its batch already left the queue.
+     */
+    flushOnHide(): void;
+    stop(): void;
+    private trim;
+    private send;
+    private backOff;
+}

package/dist/browser/transport.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserTransport = void 0;
+/** Browsers cap the combined body of in-flight keepalive requests at 64 KiB. */
+const KEEPALIVE_BYTES = 60000;
+const MAX_RETRY_DELAY_MS = 300000;
+/**
+ * Batches events and posts them to the ingest API. It never throws into the page
+ * and never blocks it: a Midline outage costs queued telemetry, not the app.
+ */
+class BrowserTransport {
+    constructor(options) {
+        this.options = options;
+        this.queue = [];
+        this.sending = false;
+        this.stopped = false;
+        this.retryAt = 0;
+        this.backoffMs = 0;
+        this.dropped = 0;
+    }
+    start() {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => void this.flush(), this.options.flushIntervalMs);
+    }
+    enqueue(event) {
+        if (this.stopped)
+            return;
+        this.queue.push(event);
+        this.trim();
+        if (this.queue.length >= this.options.maxBatchSize && Date.now() >= this.retryAt) {
+            void this.flush();
+        }
+    }
+    get size() {
+        return this.queue.length;
+    }
+    /** Sends everything queued, one batch at a time, unless Midline asked us to back off. */
+    async flush() {
+        if (this.stopped || this.sending || !this.queue.length || Date.now() < this.retryAt)
+            return;
+        this.sending = true;
+        try {
+            while (this.queue.length && !this.stopped) {
+                const batch = this.queue.splice(0, this.options.maxBatchSize);
+                const outcome = await this.send(batch, false);
+                if (outcome === "retry") {
+                    this.queue.unshift(...batch);
+                    this.trim();
+                    return;
+                }
+                if (outcome === "stop")
+                    return;
+            }
+        }
+        finally {
+            this.sending = false;
+        }
+    }
+    /**
+     * The page is being hidden and may never come back. Hands whatever is queued to
+     * keepalive requests without waiting on them; an in-flight regular flush is left
+     * alone, since its batch already left the queue.
+     */
+    flushOnHide() {
+        if (this.stopped || !this.queue.length)
+            return;
+        let budget = KEEPALIVE_BYTES;
+        while (this.queue.length) {
+            const batch = [];
+            let bytes = 12;
+            while (this.queue.length && batch.length < this.options.maxBatchSize) {
+                const size = JSON.stringify(this.queue[0]).length + 1;
+                if (batch.length && bytes + size > budget)
+                    break;
+                batch.push(this.queue.shift());
+                bytes += size;
+            }
+            budget -= bytes;
+            void this.send(batch, budget > 0);
+            if (budget <= 0)
+                break;
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.queue = [];
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    trim() {
+        const excess = this.queue.length - this.options.maxQueueSize;
+        if (excess > 0) {
+            this.queue.splice(0, excess);
+            this.dropped += excess;
+        }
+    }
+    async send(batch, keepalive) {
+        let response;
+        try {
+            response = await this.options.fetch(this.options.batchUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "X-API-Key": this.options.apiKey },
+                body: JSON.stringify({ events: batch }),
+                keepalive,
+                credentials: "omit",
+                mode: "cors",
+            });
+        }
+        catch (error) {
+            // Offline, blocked by an extension, or a server that doesn't answer CORS.
+            this.options.debug(`midline: could not reach Midline (${describe(error)}); will retry.`);
+            this.backOff();
+            return "retry";
+        }
+        const { status } = response;
+        if (status >= 200 && status < 300) {
+            this.backoffMs = 0;
+            this.retryAt = 0;
+            return "ok";
+        }
+        if (status === 401 || status === 403) {
+            const detail = await serverMessage(response);
+            this.stop();
+            this.options.onStop(`midline: the Midline server refused this key (HTTP ${status}${detail ? `: ${detail}` : ""}). ` +
+                "Browser monitoring is now off.");
+            return "stop";
+        }
+        if (status === 408 || status === 429 || status >= 500) {
+            this.backOff(parseRetryAfter(response.headers.get("retry-after")));
+            this.options.debug(`midline: Midline answered HTTP ${status}; events are kept and retried.`);
+            return "retry";
+        }
+        this.dropped += batch.length;
+        const detail = await serverMessage(response);
+        this.options.debug(`midline: Midline rejected ${batch.length} events (HTTP ${status}${detail ? `: ${detail}` : ""}).`);
+        return "drop";
+    }
+    backOff(retryAfterMs = 0) {
+        this.backoffMs = Math.min(Math.max(this.backoffMs * 2, 1000), MAX_RETRY_DELAY_MS);
+        this.retryAt = Date.now() + Math.max(this.backoffMs, Math.min(retryAfterMs, MAX_RETRY_DELAY_MS));
+    }
+}
+exports.BrowserTransport = BrowserTransport;
+function parseRetryAfter(value) {
+    if (!value)
+        return 0;
+    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()) : 0;
+}
+async function serverMessage(response) {
+    try {
+        const text = await response.text();
+        const parsed = JSON.parse(text);
+        const message = Array.isArray(parsed?.message) ? parsed.message.join("; ") : parsed?.message;
+        return typeof message === "string" ? message.slice(0, 300) : "";
+    }
+    catch {
+        return "";
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/browser/types.d.ts

@@ -0,0 +1,94 @@
+import type { EventCategory, EventSeverity } from "../types.js";
+/** Which fetch/XHR calls become events. Every call is a breadcrumb regardless. */
+export type RequestCapture = "failed" | "all" | false;
+export type ConsoleLevel = "error" | "warn" | "info" | "log" | "debug";
+/** Kept deliberately small: an id is enough to find a user's sessions, and anything more is personal data. */
+export interface MidlineUser {
+    id?: string;
+    username?: string;
+}
+export interface MidlineBrowserConfig {
+    /**
+     * A **browser key** (`pk_…`) from the Midline dashboard. Browser keys are public
+     * and only accepted from the origins listed on the key. Server keys (`ak_…`) are
+     * secrets; the SDK refuses to start with one, and the server refuses them from
+     * browsers anyway.
+     */
+    apiKey: string;
+    /** The Midline server. Default `https://api.usemidline.com`. `http://` only for localhost. */
+    endpoint?: string;
+    /** Name for this app, e.g. `checkout-web`. */
+    service?: string;
+    environment?: string;
+    /** Build or version tag, so an error can be tied to the deploy that introduced it. */
+    release?: string;
+    /** Set to false to keep the SDK inert (e.g. in local development). */
+    enabled?: boolean;
+    /** Uncaught errors and unhandled promise rejections. Default true. */
+    captureErrors?: boolean;
+    /** fetch and XMLHttpRequest calls. Default `"failed"`: 4xx, 5xx and network errors. */
+    captureRequests?: RequestCapture;
+    /**
+     * Also send console output as `console` events. `true` means `["error", "warn"]`.
+     * Default false. Wrapping console makes devtools attribute log lines to the SDK,
+     * which is why it is opt-in.
+     */
+    captureConsole?: boolean | ConsoleLevel[];
+    /** LCP, INP, CLS, FCP and TTFB, reported once when the page is first hidden. Default true. */
+    captureWebVitals?: 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
+     * when they start with `/`), RegExps against the full URL. Default: same-origin
+     * requests only, because a new header on a cross-origin call makes that API
+     * answer a CORS preflight.
+     */
+    tracePropagationTargets?: Array<string | RegExp>;
+    /** Error messages to drop. Strings match as substrings. */
+    ignoreErrors?: Array<string | RegExp>;
+    /** Request URLs never recorded, e.g. analytics beacons. Strings match as substrings. */
+    ignoreUrls?: Array<string | RegExp>;
+    /** Fraction of events sent, 0–1. Default 1. */
+    sampleRate?: number;
+    /** Ceiling on events per minute, so an error in a render loop can't flood the project. Default 120. */
+    maxEventsPerMinute?: number;
+    /** Extra field names to redact, on top of the built-in list. */
+    redactFields?: string[];
+    /**
+     * Last look at every event. Return null to drop it. Change `payload` and
+     * `metadata` freely; other unknown top-level fields are removed, because the
+     * server rejects them.
+     */
+    beforeSend?: (event: BrowserEvent) => BrowserEvent | null | undefined;
+    /** Log the SDK's own diagnostics to the console. */
+    debug?: boolean;
+    /** How often queued events are sent, in ms. Default 5000. */
+    flushIntervalMs?: number;
+    /** Events per request. Default 20. */
+    maxBatchSize?: number;
+    /** Events held while Midline is unreachable; oldest dropped past this. Default 200. */
+    maxQueueSize?: number;
+}
+/** An event as it is sent to the ingest API. */
+export interface BrowserEvent {
+    eventType: "error" | "request" | "console" | "performance" | "custom";
+    route: string;
+    method?: string;
+    statusCode?: number;
+    responseTime?: number;
+    severity: EventSeverity;
+    category?: EventCategory;
+    timestamp: string;
+    service?: string;
+    environment?: string;
+    release?: string;
+    userAgent?: string;
+    traceId?: string;
+    spanId?: string;
+    payload?: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+}
+export interface CaptureContext {
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}

package/dist/browser/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/browser/version.d.ts

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

package/dist/browser/version.js

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

package/dist/browser/vitals.d.ts

@@ -0,0 +1,16 @@
+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;
+}
+/**
+ * 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 declare function observeVitals(win: Window, onReport: (report: VitalsReport) => void): () => void;