@squasher-ai/browser 0.1.1 → 0.3.0

package/dist/_vendor/telemetry-contract/sdk/public-contract.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Customer-facing telemetry contract shared by the published JavaScript SDKs.
+ * This module intentionally contains only the documented ingestion shapes.
+ */
+export type JsonPrimitive = boolean | null | number | string;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export type Level = "fatal" | "error" | "warning" | "info" | "debug";
+export interface StackFrame {
+    filename?: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    in_app?: boolean;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+}
+export interface UserContext {
+    id?: string;
+    email?: string;
+    username?: string;
+    ip_address?: string;
+}
+export interface RequestContext {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+}
+export interface Breadcrumb {
+    timestamp?: string;
+    category?: string;
+    message?: string;
+    level?: string;
+    data?: JsonObject;
+}
+/** Event payload accepted by the documented ingestion endpoint. */
+export interface IngestEvent {
+    message: string;
+    type?: string;
+    stack?: string;
+    frames?: StackFrame[];
+    level?: Level;
+    tags?: Record<string, string>;
+    user?: UserContext;
+    request?: RequestContext;
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    timestamp?: string;
+    release?: string;
+    environment?: string;
+    breadcrumbs?: Breadcrumb[];
+    extra?: Record<string, JsonValue>;
+    session_id?: string;
+    kind?: TelemetryKind;
+    event_name?: string;
+    distinct_id?: string;
+    visitor?: VisitorContext;
+    analytics?: AnalyticsContext;
+    page?: PageContext;
+    session?: SessionContext;
+    trace?: TraceContext;
+    tool_call?: ToolCallContext;
+    llm?: LlmContext;
+    attributes?: JsonObject;
+    measurements?: TelemetryMeasurement[];
+    resource_attributes?: Record<string, string>;
+}
+export interface IngestBatchPayload {
+    events: IngestEvent[];
+}
+export type IngestEventBatch = [IngestEvent, ...IngestEvent[]];
+export interface IngestBatchEnvelope {
+    events: IngestEventBatch;
+}
+export type IngestJsonBatchPayload = IngestEventBatch | IngestBatchEnvelope;
+export type IngestJsonPayload = IngestEvent | IngestJsonBatchPayload;
+/** An encoded newline-delimited JSON request body. */
+export type IngestNdjsonPayload = string;
+export type IngestRequestPayload = IngestJsonPayload | IngestNdjsonPayload;
+export type TelemetryKind = "error" | "log" | "analytics" | "identify" | "page" | "screen" | "visitor" | "agent_session" | "agent_span" | "tool_call" | "llm_generation" | "agent_score";
+export interface VisitorContext {
+    visitor_id?: string;
+    anonymous_id?: string;
+    account_id?: string;
+}
+export interface AnalyticsContext {
+    event?: string;
+    category?: string;
+    funnel?: string;
+    step?: string;
+    properties?: JsonObject;
+}
+export interface PageContext {
+    name?: string;
+    path?: string;
+    title?: string;
+    referrer?: string;
+    search?: string;
+    screen_class?: string;
+}
+export interface SessionContext {
+    session_type?: string;
+    agent_id?: string;
+    run_id?: string;
+    workflow_id?: string;
+    step_id?: string;
+    status?: string;
+    duration_ms?: number;
+}
+export interface TraceContext {
+    trace_id?: string;
+    span_id?: string;
+    parent_span_id?: string;
+    span_name?: string;
+    span_kind?: string;
+    status?: string;
+    duration_ms?: number;
+}
+export interface ToolCallContext {
+    name?: string;
+    input?: JsonObject;
+    output?: JsonObject;
+    status?: string;
+    duration_ms?: number;
+}
+export interface LlmContext {
+    provider?: string;
+    model?: string;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    cached_input_tokens?: number;
+    cost_usd?: number;
+    latency_ms?: number;
+    status?: string;
+    input?: JsonObject;
+    output?: JsonObject;
+}
+export interface TelemetryMeasurement {
+    name: string;
+    value: number;
+    unit?: string;
+}
+/** Outcome-aware SDK sampling. Errors and slow operations are kept by default. */
+export interface TelemetrySamplingConfig {
+    successRate?: number;
+    errorRate?: number;
+    slowRate?: number;
+    slowThresholdMs?: number;
+    alwaysSampleUserIds?: string[];
+    alwaysSampleReleases?: string[];
+}
+export interface IngestResponse {
+    id: string;
+    status: string;
+    accepted?: number;
+}
+export interface SdkConfig {
+    apiKey: string;
+    projectId: string;
+    endpoint?: string;
+    environment?: string;
+    release?: string;
+    debug?: boolean;
+    sampling?: TelemetrySamplingConfig;
+    beforeSend?: (event: IngestEvent) => IngestEvent | null;
+    maxBreadcrumbs?: number;
+    resourceAttributes?: Record<string, string>;
+    autoFlushIntervalMs?: number;
+}

package/dist/_vendor/telemetry-contract/sdk/public-contract.js

@@ -0,0 +1,5 @@
+/**
+ * Customer-facing telemetry contract shared by the published JavaScript SDKs.
+ * This module intentionally contains only the documented ingestion shapes.
+ */
+export {};

package/dist/autocapture.d.ts

@@ -1,21 +1,16 @@
 /**
- * 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
+ * Auto-capture breadcrumbs. Categories emitted:
+ *   - "navigation" — pushState/replaceState/popstate
+ *   - "ui.click"   — clicks on elements
+ *   - "fetch"      — 4xx/5xx fetch responses
+ *   - "console"    — console.error / console.warn calls
  */
-import type { Breadcrumb } from "./types";
-export type BreadcrumbCallback = (crumb: Omit<Breadcrumb, "timestamp">) => void;
-/**
- * Install all auto-capture hooks.
- * Returns a cleanup function to remove all hooks and restore originals.
- */
-export declare function installAutocapture(onBreadcrumb: BreadcrumbCallback): () => void;
-//# sourceMappingURL=autocapture.d.ts.map
+import { type BreadcrumbCallback } from "./console-capture.js";
+import type { BrowserErrorEvent } from "./types.js";
+export type { BreadcrumbCallback } from "./console-capture.js";
+export interface AutocaptureOptions {
+    captureBreadcrumbs?: boolean;
+    onConsoleError?: (event: BrowserErrorEvent) => void;
+}
+/** Installs all hooks. Returned function removes them and restores originals. */
+export declare function installAutocapture(onBreadcrumb: BreadcrumbCallback, options?: AutocaptureOptions): () => void;

package/dist/autocapture.js

@@ -1,26 +1,28 @@
 /**
- * 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
+ * Auto-capture breadcrumbs. Categories emitted:
+ *   - "navigation" — pushState/replaceState/popstate
+ *   - "ui.click"   — clicks on elements
+ *   - "fetch"      — 4xx/5xx fetch responses
+ *   - "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) {
+import { attemptAsync } from "./_vendor/result-runtime/attempt.js";
+import { readRuntimeProperty, readRuntimeString } from "./_vendor/sdk-runtime/runtime/public-sdk-runtime.js";
+import { captureConsole } from "./console-capture.js";
+/** Installs all hooks. Returned function removes them and restores originals. */
+export function installAutocapture(onBreadcrumb, options = {}) {
     const cleanups = [];
-    cleanups.push(captureNavigation(onBreadcrumb));
-    cleanups.push(captureClicks(onBreadcrumb));
-    cleanups.push(captureFetch(onBreadcrumb));
-    cleanups.push(captureConsole(onBreadcrumb));
+    const captureBreadcrumbs = options.captureBreadcrumbs ?? true;
+    if (captureBreadcrumbs) {
+        cleanups.push(captureNavigation(onBreadcrumb));
+        cleanups.push(captureClicks(onBreadcrumb));
+        cleanups.push(captureFetch(onBreadcrumb));
+    }
+    if (captureBreadcrumbs || options.onConsoleError) {
+        cleanups.push(captureConsole(onBreadcrumb, {
+            captureBreadcrumbs,
+            onConsoleError: options.onConsoleError,
+        }));
+    }
     return () => {
         for (const cleanup of cleanups) {
             cleanup();
@@ -43,13 +45,13 @@ function captureNavigation(onBreadcrumb) {
     };
     // Patch history.pushState
     const origPushState = history.pushState.bind(history);
-    history.pushState = function (...args) {
+    history.pushState = (...args) => {
         origPushState(...args);
         emitNavCrumb();
     };
     // Patch history.replaceState
     const origReplaceState = history.replaceState.bind(history);
-    history.replaceState = function (...args) {
+    history.replaceState = (...args) => {
         origReplaceState(...args);
         emitNavCrumb();
     };
@@ -65,20 +67,21 @@ function captureNavigation(onBreadcrumb) {
 // ─── Clicks ─────────────────────────────────────────────────────────────
 function captureClicks(onBreadcrumb) {
     const handler = (event) => {
-        const target = event.target;
+        const target = readClickTarget(event.target);
         if (!target)
             return;
         const descriptor = describeElement(target);
         if (!descriptor)
             return;
+        const data = { tag: target.tagName.toLowerCase() };
+        if (target.id)
+            data.id = target.id;
+        if (target.className)
+            data.className = target.className;
         onBreadcrumb({
             category: "ui.click",
             message: descriptor,
-            data: {
-                tag: target.tagName?.toLowerCase(),
-                id: target.id || undefined,
-                className: target.className || undefined,
-            },
+            data,
         });
     };
     // Use capture phase to catch clicks even if stopPropagation is called
@@ -87,27 +90,35 @@ function captureClicks(onBreadcrumb) {
         document.removeEventListener("click", handler, true);
     };
 }
+function readClickTarget(target) {
+    const tagName = readRuntimeString(readRuntimeProperty(target, "tagName"));
+    if (!tagName)
+        return null;
+    return {
+        className: readRuntimeString(readRuntimeProperty(target, "className")) ?? "",
+        id: readRuntimeString(readRuntimeProperty(target, "id")) ?? "",
+        tagName,
+        textContent: readRuntimeString(readRuntimeProperty(target, "textContent")) ?? "",
+    };
+}
 /**
  * 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;
+    const tag = el.tagName.toLowerCase();
     let desc = tag;
-    const htmlEl = el;
-    if (htmlEl.id) {
-        desc += `#${htmlEl.id}`;
+    if (el.id) {
+        desc += `#${el.id}`;
     }
-    if (htmlEl.className && typeof htmlEl.className === "string") {
-        const classes = htmlEl.className.trim().split(/\s+/).slice(0, 2).join(".");
+    if (el.className) {
+        const classes = el.className.trim().split(/\s+/).slice(0, 2).join(".");
         if (classes) {
             desc += `.${classes}`;
         }
     }
     // Add text content for buttons/links (truncated)
-    const textContent = htmlEl.textContent?.trim();
+    const textContent = el.textContent?.trim();
     if (textContent && (tag === "button" || tag === "a")) {
         const truncated = textContent.length > 30 ? `${textContent.slice(0, 30)}...` : textContent;
         desc += `[${truncated}]`;
@@ -116,76 +127,47 @@ function describeElement(el) {
 }
 // ─── Fetch ──────────────────────────────────────────────────────────────
 function captureFetch(onBreadcrumb) {
-    if (typeof window === "undefined" || !window.fetch)
+    if (!globalThis.window?.fetch)
         return () => { };
     const origFetch = window.fetch.bind(window);
-    window.fetch = async function (input, init) {
+    window.fetch = async (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) {
+        const url = input instanceof URL ? input.href : input instanceof Request ? input.url : String(input);
+        return attemptAsync({
+            try: async () => {
+                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: ({ cause, error }) => {
+                // Network error
                 onBreadcrumb({
                     category: "fetch",
-                    message: `${method} ${url} [${response.status}]`,
-                    level: response.status >= 500 ? "error" : "warning",
+                    message: `${method} ${url} [network error]`,
+                    level: "error",
                     data: {
                         method,
                         url,
-                        status: response.status,
+                        error: error.message,
                     },
                 });
-            }
-            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",
+                throw cause;
+            },
         });
-        origWarn(...args);
     };
     return () => {
-        console.error = origError;
-        console.warn = origWarn;
+        window.fetch = origFetch;
     };
 }

package/dist/client.d.ts

@@ -1,15 +1,6 @@
-/**
- * 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";
+import { type BrowserClientRuntime } from "./runtime/client.js";
+import type { Breadcrumb, BrowserConfig, BrowserErrorEvent, JsonObject, Level, UserContext } from "./types.js";
+import { type ExternalVitalInput } from "./vitals.js";
 export declare class BrowserClient {
     private config;
     private transport;
@@ -19,12 +10,13 @@ export declare class BrowserClient {
     private disabled;
     private cleanups;
     private replayRecorder;
-    constructor(config: BrowserConfig);
+    private vitalsHandle;
+    constructor(config: BrowserConfig, runtime?: BrowserClientRuntime);
     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;
+    captureError(error: Error, extra?: JsonObject): void;
     captureMessage(message: string, level?: Level): void;
     captureTelemetry(event: BrowserErrorEvent): void;
     track(eventName: string, properties?: JsonObject, context?: Partial<BrowserErrorEvent>): void;
@@ -34,13 +26,13 @@ export declare class BrowserClient {
     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.
-     */
+    /** Record a web vital from an external collector (e.g. Next.js `useReportWebVitals`). */
+    recordWebVital(metric: ExternalVitalInput, route?: string): void;
+    /** Stop the SDK's native `web-vitals` collector to avoid double-counting. */
+    suppressNativeVitalsCollection(): void;
+    private vitalsConfig;
+    /** Flush vitals and stop timers. Call before unmounting a SPA. */
     close(): void;
-    private shouldSample;
     /** Enrich an error event with current context and send it. */
     private sendErrorEvent;
 }
-//# sourceMappingURL=client.d.ts.map