@squasher-ai/browser 0.1.0

package/dist/autocapture.js

@@ -0,0 +1,191 @@
+/**
+ * Auto-capture breadcrumbs for navigation, clicks, and fetch errors.
+ *
+ * Breadcrumbs are lightweight events that provide context about what the
+ * user was doing before an error occurred. They are attached to error
+ * events to help with debugging and AI triage.
+ *
+ * Categories:
+ *   - "navigation" — route changes (pushState, replaceState, popstate)
+ *   - "ui.click" — user clicks on elements
+ *   - "fetch" — failed fetch requests (4xx/5xx)
+ *   - "console" — console.error / console.warn calls
+ */
+/**
+ * Install all auto-capture hooks.
+ * Returns a cleanup function to remove all hooks and restore originals.
+ */
+export function installAutocapture(onBreadcrumb) {
+    const cleanups = [];
+    cleanups.push(captureNavigation(onBreadcrumb));
+    cleanups.push(captureClicks(onBreadcrumb));
+    cleanups.push(captureFetch(onBreadcrumb));
+    cleanups.push(captureConsole(onBreadcrumb));
+    return () => {
+        for (const cleanup of cleanups) {
+            cleanup();
+        }
+    };
+}
+// ─── Navigation ───────────────────────────────────────────────────────────
+function captureNavigation(onBreadcrumb) {
+    let lastUrl = location.href;
+    const emitNavCrumb = () => {
+        const newUrl = location.href;
+        if (newUrl !== lastUrl) {
+            onBreadcrumb({
+                category: "navigation",
+                message: `${lastUrl} → ${newUrl}`,
+                data: { from: lastUrl, to: newUrl },
+            });
+            lastUrl = newUrl;
+        }
+    };
+    // Patch history.pushState
+    const origPushState = history.pushState.bind(history);
+    history.pushState = function (...args) {
+        origPushState(...args);
+        emitNavCrumb();
+    };
+    // Patch history.replaceState
+    const origReplaceState = history.replaceState.bind(history);
+    history.replaceState = function (...args) {
+        origReplaceState(...args);
+        emitNavCrumb();
+    };
+    // Listen to popstate (back/forward)
+    const popstateHandler = () => emitNavCrumb();
+    window.addEventListener("popstate", popstateHandler);
+    return () => {
+        history.pushState = origPushState;
+        history.replaceState = origReplaceState;
+        window.removeEventListener("popstate", popstateHandler);
+    };
+}
+// ─── Clicks ─────────────────────────────────────────────────────────────
+function captureClicks(onBreadcrumb) {
+    const handler = (event) => {
+        const target = event.target;
+        if (!target)
+            return;
+        const descriptor = describeElement(target);
+        if (!descriptor)
+            return;
+        onBreadcrumb({
+            category: "ui.click",
+            message: descriptor,
+            data: {
+                tag: target.tagName?.toLowerCase(),
+                id: target.id || undefined,
+                className: target.className || undefined,
+            },
+        });
+    };
+    // Use capture phase to catch clicks even if stopPropagation is called
+    document.addEventListener("click", handler, true);
+    return () => {
+        document.removeEventListener("click", handler, true);
+    };
+}
+/**
+ * Build a human-readable descriptor for a DOM element.
+ * e.g. "button#submit-btn.primary" or "a.nav-link"
+ */
+function describeElement(el) {
+    const tag = el.tagName?.toLowerCase();
+    if (!tag)
+        return null;
+    let desc = tag;
+    const htmlEl = el;
+    if (htmlEl.id) {
+        desc += `#${htmlEl.id}`;
+    }
+    if (htmlEl.className && typeof htmlEl.className === "string") {
+        const classes = htmlEl.className.trim().split(/\s+/).slice(0, 2).join(".");
+        if (classes) {
+            desc += `.${classes}`;
+        }
+    }
+    // Add text content for buttons/links (truncated)
+    const textContent = htmlEl.textContent?.trim();
+    if (textContent && (tag === "button" || tag === "a")) {
+        const truncated = textContent.length > 30 ? `${textContent.slice(0, 30)}...` : textContent;
+        desc += `[${truncated}]`;
+    }
+    return desc;
+}
+// ─── Fetch ──────────────────────────────────────────────────────────────
+function captureFetch(onBreadcrumb) {
+    if (typeof window === "undefined" || !window.fetch)
+        return () => { };
+    const origFetch = window.fetch.bind(window);
+    window.fetch = async function (input, init) {
+        const method = init?.method?.toUpperCase() || "GET";
+        const url = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input instanceof Request
+                    ? input.url
+                    : String(input);
+        try {
+            const response = await origFetch(input, init);
+            // Only breadcrumb on error responses (4xx/5xx)
+            if (response.status >= 400) {
+                onBreadcrumb({
+                    category: "fetch",
+                    message: `${method} ${url} [${response.status}]`,
+                    level: response.status >= 500 ? "error" : "warning",
+                    data: {
+                        method,
+                        url,
+                        status: response.status,
+                    },
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            // Network error
+            onBreadcrumb({
+                category: "fetch",
+                message: `${method} ${url} [network error]`,
+                level: "error",
+                data: {
+                    method,
+                    url,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
+    };
+    return () => {
+        window.fetch = origFetch;
+    };
+}
+// ─── Console ────────────────────────────────────────────────────────────
+function captureConsole(onBreadcrumb) {
+    const origError = console.error.bind(console);
+    const origWarn = console.warn.bind(console);
+    console.error = (...args) => {
+        onBreadcrumb({
+            category: "console",
+            message: args.map(String).join(" ").slice(0, 200),
+            level: "error",
+        });
+        origError(...args);
+    };
+    console.warn = (...args) => {
+        onBreadcrumb({
+            category: "console",
+            message: args.map(String).join(" ").slice(0, 200),
+            level: "warning",
+        });
+        origWarn(...args);
+    };
+    return () => {
+        console.error = origError;
+        console.warn = origWarn;
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * BrowserClient — the core SDK client for browser environments.
+ *
+ * Manages:
+ *   - Configuration with sensible defaults
+ *   - User context, tags, and breadcrumbs
+ *   - Web Vitals collection (via vitals.ts)
+ *   - Global error capture (via errors.ts)
+ *   - Auto-capture breadcrumbs (via autocapture.ts)
+ *   - Transport (via transport.ts)
+ */
+import type { Breadcrumb, BrowserConfig, BrowserErrorEvent, JsonObject, Level, UserContext } from "./types";
+export declare class BrowserClient {
+    private config;
+    private transport;
+    private breadcrumbs;
+    private user;
+    private tags;
+    private disabled;
+    private cleanups;
+    private replayRecorder;
+    constructor(config: BrowserConfig);
+    setUser(user: UserContext | undefined): void;
+    setTag(key: string, value: string): void;
+    setTags(tags: Record<string, string>): void;
+    addBreadcrumb(crumb: Omit<Breadcrumb, "timestamp">): void;
+    captureError(error: Error, extra?: Record<string, unknown>): void;
+    captureMessage(message: string, level?: Level): void;
+    captureTelemetry(event: BrowserErrorEvent): void;
+    track(eventName: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+    identify(distinctId: string, traits?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+    page(name: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+    screen(name: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+    captureSpan(name: string, context?: Partial<BrowserErrorEvent>): void;
+    captureToolCall(name: string, context?: Partial<BrowserErrorEvent>): void;
+    captureGeneration(message: string, context?: Partial<BrowserErrorEvent>): void;
+    /**
+     * Flush remaining vitals and stop all timers.
+     * Call this before unmounting a SPA or during cleanup.
+     */
+    close(): void;
+    private shouldSample;
+    /** Enrich an error event with current context and send it. */
+    private sendErrorEvent;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiBH,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,KAAK,EAEL,WAAW,EACZ,MAAM,SAAS,CAAC;AAiDjB,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,cAAc,CAA+B;gBAEzC,MAAM,EAAE,aAAa;IAmFjC,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI;IAI5C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAI3C,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG,IAAI;IAYzD,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIjE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,KAAc,GAAG,IAAI;IAI5D,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAMhD,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,UAAU,EACvB,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GACvC,IAAI;IAIP,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,UAAU,EACnB,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GACvC,IAAI;IAKP,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAAG,IAAI;IAI3F,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAAG,IAAI;IAI7F,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAAG,IAAI;IAIzE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAAG,IAAI;IAI7E,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAAG,IAAI;IAMlF;;;OAGG;IACH,KAAK,IAAI,IAAI;IAab,OAAO,CAAC,YAAY;IAMpB,8DAA8D;IAC9D,OAAO,CAAC,cAAc;CAcvB"}

package/dist/client.js

@@ -0,0 +1,215 @@
+/**
+ * BrowserClient — the core SDK client for browser environments.
+ *
+ * Manages:
+ *   - Configuration with sensible defaults
+ *   - User context, tags, and breadcrumbs
+ *   - Web Vitals collection (via vitals.ts)
+ *   - Global error capture (via errors.ts)
+ *   - Auto-capture breadcrumbs (via autocapture.ts)
+ *   - Transport (via transport.ts)
+ */
+import { installAutocapture } from "./autocapture";
+import { buildErrorEvent, buildMessageEvent, installGlobalErrorHandlers } from "./errors";
+import { ReplayRecorder } from "./replay";
+import { buildGenerationEvent, buildIdentifyEvent, buildPageEvent, buildScreenEvent, buildSpanEvent, buildToolCallEvent, buildTrackEvent, mergeIdentifiedUser, prepareBrowserEvent, } from "./telemetry";
+import { Transport } from "./transport";
+import { startVitalsCollection } from "./vitals";
+const DEFAULT_ENDPOINT = "https://ingest.squasher.ai";
+function resolveConfig(config) {
+    return {
+        apiKey: config.apiKey,
+        projectId: config.projectId,
+        endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+        environment: config.environment,
+        release: config.release,
+        debug: config.debug ?? false,
+        sampleRate: config.sampleRate ?? 1,
+        vitalsSampleRate: config.vitalsSampleRate ?? 1,
+        enableVitals: config.enableVitals ?? true,
+        enableErrorCapture: config.enableErrorCapture ?? true,
+        enableAutoBreadcrumbs: config.enableAutoBreadcrumbs ?? true,
+        beforeSend: config.beforeSend,
+        maxBreadcrumbs: config.maxBreadcrumbs ?? 30,
+        vitalsBufferSize: config.vitalsBufferSize ?? 10,
+        vitalsFlushIntervalMs: config.vitalsFlushIntervalMs ?? 10_000,
+        replayEnabled: config.replay?.enabled ?? false,
+        replaySampleRate: config.replay?.sampleRate ?? 1,
+        replayPrivacy: config.replay?.privacy,
+    };
+}
+export class BrowserClient {
+    config;
+    transport;
+    breadcrumbs = [];
+    user;
+    tags = {};
+    disabled;
+    cleanups = [];
+    replayRecorder = null;
+    constructor(config) {
+        if (!config.apiKey)
+            throw new Error("Squasher: apiKey is required");
+        if (!config.projectId)
+            throw new Error("Squasher: projectId is required");
+        this.config = resolveConfig(config);
+        this.disabled = config.apiKey.length === 0 || config.projectId.length === 0;
+        if (this.disabled) {
+            if (this.config.debug) {
+                console.warn("[squasher] SDK initialized in disabled mode");
+            }
+            // Create a no-op transport
+            this.transport = new Transport({
+                endpoint: this.config.endpoint,
+                projectId: this.config.projectId,
+                apiKey: this.config.apiKey,
+                debug: this.config.debug,
+                vitalsBufferSize: this.config.vitalsBufferSize,
+                vitalsFlushIntervalMs: this.config.vitalsFlushIntervalMs,
+            });
+            return;
+        }
+        // Initialize transport
+        this.transport = new Transport({
+            endpoint: this.config.endpoint,
+            projectId: this.config.projectId,
+            apiKey: this.config.apiKey,
+            debug: this.config.debug,
+            vitalsBufferSize: this.config.vitalsBufferSize,
+            vitalsFlushIntervalMs: this.config.vitalsFlushIntervalMs,
+        });
+        // Start Web Vitals collection
+        if (this.config.enableVitals) {
+            startVitalsCollection(this.transport, {
+                sampleRate: this.config.vitalsSampleRate,
+                environment: this.config.environment,
+                release: this.config.release,
+                debug: this.config.debug,
+            });
+        }
+        // Install global error handlers
+        if (this.config.enableErrorCapture) {
+            const cleanup = installGlobalErrorHandlers((event) => {
+                this.sendErrorEvent(event);
+            });
+            this.cleanups.push(cleanup);
+        }
+        // Install auto-capture breadcrumbs
+        if (this.config.enableAutoBreadcrumbs) {
+            const cleanup = installAutocapture((crumb) => {
+                this.addBreadcrumb(crumb);
+            });
+            this.cleanups.push(cleanup);
+        }
+        if (this.config.replayEnabled) {
+            this.replayRecorder = new ReplayRecorder({
+                endpoint: this.config.endpoint,
+                projectId: this.config.projectId,
+                apiKey: this.config.apiKey,
+                debug: this.config.debug,
+                sampleRate: this.config.replaySampleRate,
+                privacy: this.config.replayPrivacy,
+            });
+        }
+        if (this.config.debug) {
+            console.log("[squasher] Browser SDK initialized", {
+                projectId: this.config.projectId,
+                vitals: this.config.enableVitals,
+                errorCapture: this.config.enableErrorCapture,
+                autoBreadcrumbs: this.config.enableAutoBreadcrumbs,
+                replay: this.config.replayEnabled,
+            });
+        }
+    }
+    // ─── Context ──────────────────────────────────────────────────────────
+    setUser(user) {
+        this.user = user;
+    }
+    setTag(key, value) {
+        this.tags[key] = value;
+    }
+    setTags(tags) {
+        Object.assign(this.tags, tags);
+    }
+    addBreadcrumb(crumb) {
+        this.breadcrumbs.push({
+            ...crumb,
+            timestamp: new Date().toISOString(),
+        });
+        if (this.breadcrumbs.length > this.config.maxBreadcrumbs) {
+            this.breadcrumbs = this.breadcrumbs.slice(-this.config.maxBreadcrumbs);
+        }
+    }
+    // ─── Capture ──────────────────────────────────────────────────────────
+    captureError(error, extra) {
+        this.captureTelemetry(buildErrorEvent(error, extra));
+    }
+    captureMessage(message, level = "info") {
+        this.captureTelemetry(buildMessageEvent(message, level));
+    }
+    captureTelemetry(event) {
+        if (this.disabled)
+            return;
+        if (!this.shouldSample())
+            return;
+        this.sendErrorEvent(event);
+    }
+    track(eventName, properties, context = {}) {
+        this.captureTelemetry(buildTrackEvent(eventName, properties, context));
+    }
+    identify(distinctId, traits, context = {}) {
+        this.user = mergeIdentifiedUser(this.user, context.user, distinctId);
+        this.captureTelemetry(buildIdentifyEvent(distinctId, traits, context));
+    }
+    page(name, properties, context = {}) {
+        this.captureTelemetry(buildPageEvent(name, properties, context));
+    }
+    screen(name, properties, context = {}) {
+        this.captureTelemetry(buildScreenEvent(name, properties, context));
+    }
+    captureSpan(name, context = {}) {
+        this.captureTelemetry(buildSpanEvent(name, context));
+    }
+    captureToolCall(name, context = {}) {
+        this.captureTelemetry(buildToolCallEvent(name, context));
+    }
+    captureGeneration(message, context = {}) {
+        this.captureTelemetry(buildGenerationEvent(message, context));
+    }
+    // ─── Lifecycle ────────────────────────────────────────────────────────
+    /**
+     * Flush remaining vitals and stop all timers.
+     * Call this before unmounting a SPA or during cleanup.
+     */
+    close() {
+        this.replayRecorder?.dispose();
+        this.replayRecorder = null;
+        for (const cleanup of this.cleanups) {
+            cleanup();
+        }
+        this.cleanups = [];
+        this.transport.dispose();
+    }
+    // ─── Private ──────────────────────────────────────────────────────────
+    shouldSample() {
+        if (this.config.sampleRate >= 1)
+            return true;
+        if (this.config.sampleRate <= 0)
+            return false;
+        return Math.random() < this.config.sampleRate;
+    }
+    /** Enrich an error event with current context and send it. */
+    sendErrorEvent(event) {
+        const prepared = prepareBrowserEvent(event, {
+            beforeSend: this.config.beforeSend,
+            breadcrumbs: this.breadcrumbs,
+            environment: this.config.environment,
+            release: this.config.release,
+            tags: this.tags,
+            user: this.user,
+        });
+        if (prepared) {
+            this.transport.sendEvent(prepared);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Browser error capture.
+ *
+ * Installs global error handlers:
+ *   - window.addEventListener("error") — sync errors
+ *   - window.addEventListener("unhandledrejection") — promise rejections
+ *
+ * Parses Error.stack into StackFrame[] using the same regex pattern as
+ * @squasher-ai/node. In-app heuristic: node_modules = not in_app.
+ */
+import type { BrowserErrorEvent, StackFrame } from "./types";
+/**
+ * Parse an Error.stack string into structured StackFrame[].
+ */
+export declare function parseStack(stack?: string): StackFrame[] | undefined;
+/**
+ * Build a BrowserErrorEvent from an Error object.
+ */
+export declare function buildErrorEvent(error: Error, extra?: Record<string, unknown>): BrowserErrorEvent;
+/**
+ * Build a BrowserErrorEvent from a string message.
+ */
+export declare function buildMessageEvent(message: string, level?: BrowserErrorEvent["level"]): BrowserErrorEvent;
+/**
+ * Install global error handlers.
+ * Returns a cleanup function to remove the handlers.
+ */
+export declare function installGlobalErrorHandlers(onError: (event: BrowserErrorEvent) => void): () => void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAW7D;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,SAAS,CAkCnE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAWhG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,iBAAiB,CAAC,OAAO,CAAU,GACzC,iBAAiB,CAOnB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAC1C,MAAM,IAAI,CAuCZ"}

package/dist/errors.js

@@ -0,0 +1,111 @@
+/**
+ * Browser error capture.
+ *
+ * Installs global error handlers:
+ *   - window.addEventListener("error") — sync errors
+ *   - window.addEventListener("unhandledrejection") — promise rejections
+ *
+ * Parses Error.stack into StackFrame[] using the same regex pattern as
+ * @squasher-ai/node. In-app heuristic: node_modules = not in_app.
+ */
+const SDK_NAME = "@squasher-ai/browser";
+const SDK_VERSION = "0.1.0";
+/** Stack trace line regex — works for V8 (Chrome, Node) and SpiderMonkey (Firefox). */
+const STACK_LINE_RE = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?/;
+/** Firefox stack format: "functionName@filename:line:col" */
+const FIREFOX_STACK_RE = /^(.+?)@(.+?):(\d+):(\d+)$/;
+/**
+ * Parse an Error.stack string into structured StackFrame[].
+ */
+export function parseStack(stack) {
+    if (!stack)
+        return undefined;
+    const lines = stack.split("\n").slice(1);
+    const frames = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Try V8 format first
+        let match = trimmed.match(STACK_LINE_RE);
+        if (!match) {
+            // Try Firefox format
+            match = trimmed.match(FIREFOX_STACK_RE);
+        }
+        if (!match)
+            continue;
+        const [, fn, filename, lineno, colno] = match;
+        const isExternal = filename?.includes("node_modules") ||
+            filename?.includes("extensions/") ||
+            filename?.startsWith("chrome-extension://") ||
+            false;
+        frames.push({
+            function: fn || "<anonymous>",
+            filename,
+            lineno: lineno ? parseInt(lineno, 10) : undefined,
+            colno: colno ? parseInt(colno, 10) : undefined,
+            in_app: !isExternal,
+        });
+    }
+    return frames.length > 0 ? frames : undefined;
+}
+/**
+ * Build a BrowserErrorEvent from an Error object.
+ */
+export function buildErrorEvent(error, extra) {
+    return {
+        message: error.message || String(error),
+        type: error.name,
+        stack: error.stack,
+        frames: parseStack(error.stack),
+        level: "error",
+        sdk: { name: SDK_NAME, version: SDK_VERSION },
+        timestamp: new Date().toISOString(),
+        extra,
+    };
+}
+/**
+ * Build a BrowserErrorEvent from a string message.
+ */
+export function buildMessageEvent(message, level = "info") {
+    return {
+        message,
+        level,
+        sdk: { name: SDK_NAME, version: SDK_VERSION },
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Install global error handlers.
+ * Returns a cleanup function to remove the handlers.
+ */
+export function installGlobalErrorHandlers(onError) {
+    const errorHandler = (event) => {
+        // Ignore errors from browser extensions and cross-origin scripts
+        if (!event.error && !event.message)
+            return;
+        const error = event.error instanceof Error ? event.error : new Error(event.message || "Unknown error");
+        const browserEvent = buildErrorEvent(error, {
+            filename: event.filename,
+            lineno: event.lineno,
+            colno: event.colno,
+        });
+        browserEvent.level = "error";
+        onError(browserEvent);
+    };
+    const rejectionHandler = (event) => {
+        const reason = event.reason;
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        const browserEvent = buildErrorEvent(error);
+        browserEvent.level = "error";
+        browserEvent.type =
+            browserEvent.type === "Error"
+                ? "UnhandledRejection"
+                : `UnhandledRejection(${browserEvent.type})`;
+        onError(browserEvent);
+    };
+    window.addEventListener("error", errorHandler);
+    window.addEventListener("unhandledrejection", rejectionHandler);
+    return () => {
+        window.removeEventListener("error", errorHandler);
+        window.removeEventListener("unhandledrejection", rejectionHandler);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @squasher-ai/browser — Browser SDK for Squasher error monitoring + Web Vitals.
+ *
+ * Lightweight (<5KB gzip) browser SDK that captures:
+ *   - Core Web Vitals (LCP, CLS, INP, FCP, TTFB)
+ *   - JavaScript errors (window.onerror, unhandledrejection)
+ *   - Navigation breadcrumbs, click breadcrumbs, fetch error breadcrumbs
+ *   - Session context for error ↔ vitals correlation
+ *
+ * Usage:
+ *   import { init, captureError } from '@squasher-ai/browser';
+ *
+ *   init({
+ *     apiKey: 'sq_pk_...',
+ *     projectId: 'your-project-id',
+ *     environment: 'production',
+ *   });
+ *
+ *   // Errors are captured automatically via global handlers.
+ *   // Web Vitals are collected and sent automatically.
+ *   // Manual capture:
+ *   captureError(new Error('Something went wrong'));
+ */
+export { BrowserClient } from "./client";
+export type { AnalyticsContext, Breadcrumb, BrowserConfig, BrowserErrorEvent, DeviceType, IngestBatchPayload, IngestResponse, JsonObject, LlmContext, Level, PageContext, ReplayConfig, ReplayPrivacyConfig, SessionContext, StackFrame, TelemetryKind, TelemetryMeasurement, ToolCallContext, UserContext, VitalEvent, VitalMetricName, VitalRating, TraceContext, VisitorContext, VitalsPayload, } from "./types";
+import { BrowserClient } from "./client";
+import type { Breadcrumb, BrowserConfig, BrowserErrorEvent, JsonObject, Level, UserContext } from "./types";
+/** Initialize the global Squasher browser client. Throws if called twice. */
+export declare function init(config: BrowserConfig): BrowserClient;
+/** Get the global client (throws if not initialized). */
+export declare function getClient(): BrowserClient;
+/** Capture an error using the global client. */
+export declare function captureError(error: Error, extra?: Record<string, unknown>): void;
+/** Capture a message using the global client. */
+export declare function captureMessage(message: string, level?: Level): void;
+/** Capture a generalized telemetry event using the global client. */
+export declare function captureTelemetry(event: BrowserErrorEvent): void;
+/** Track a product analytics event using the global client. */
+export declare function track(eventName: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+/** Identify a distinct user or visitor using the global client. */
+export declare function identify(distinctId: string, traits?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+/** Capture a page navigation event using the global client. */
+export declare function page(name: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+/** Capture a screen event using the global client. */
+export declare function screen(name: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
+/** Capture an agent span using the global client. */
+export declare function captureSpan(name: string, context?: Partial<BrowserErrorEvent>): void;
+/** Capture a tool call using the global client. */
+export declare function captureToolCall(name: string, context?: Partial<BrowserErrorEvent>): void;
+/** Capture an LLM generation event using the global client. */
+export declare function captureGeneration(message: string, context?: Partial<BrowserErrorEvent>): void;
+/** Set user context on the global client. */
+export declare function setUser(user: UserContext | undefined): void;
+/** Set a single tag on the global client. */
+export declare function setTag(key: string, value: string): void;
+/** Set multiple tags on the global client. */
+export declare function setTags(tags: Record<string, string>): void;
+/** Add a breadcrumb on the global client. */
+export declare function addBreadcrumb(crumb: Omit<Breadcrumb, "timestamp">): void;
+/** Close the global client (stop timers, flush vitals, remove handlers). */
+export declare function close(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}