@squasher-ai/browser 0.1.1 → 0.3.0

package/dist/transport.d.ts

@@ -1,19 +1,14 @@
 /**
- * Transport layer for the browser SDK.
+ * Browser transport.
  *
- * Two send paths:
- *   1. Errors → POST /v1/ingest/{project_id} (immediate, same wire format as sdk-node)
- *   2. Vitals → POST /v1/vitals/{project_id} (batched array)
+ * - Errors → POST /v1/ingest/{project_id} (per-event, immediate).
+ * - Vitals → POST /v1/vitals/{project_id} (batched).
  *
- * Primary transport: navigator.sendBeacon() — fire-and-forget, survives page unload.
- * Fallback: fetch() with keepalive: true.
- *
- * Vitals are buffered and flushed on:
- *   - Buffer reaching vitalsBufferSize (default: 10)
- *   - Timer tick (default: 10s)
- *   - Page visibility change to "hidden" (user leaving)
+ * Uses navigator.sendBeacon when available so requests survive page unload,
+ * falling back to `fetch({ keepalive: true })`. Vitals flush on buffer full,
+ * interval tick, and page visibilitychange/pagehide.
  */
-import type { BrowserErrorEvent, VitalEvent } from "./types";
+import type { BrowserErrorEvent, VitalEvent } from "./types.js";
 export interface TransportConfig {
     endpoint: string;
     projectId: string;
@@ -28,20 +23,16 @@ export declare class Transport {
     private flushTimer;
     private disposed;
     constructor(config: TransportConfig);
-    /** Send a single telemetry event immediately. Fire-and-forget. */
+    /** Fire-and-forget. */
     sendEvent(event: BrowserErrorEvent): void;
-    /** Backward-compatible alias for error events. */
+    /** @deprecated use {@link sendEvent}. */
     sendError(event: BrowserErrorEvent): void;
-    /** Buffer a vital event. Auto-flushes when buffer is full. */
     enqueueVital(event: VitalEvent): void;
-    /** Flush all buffered vitals immediately. */
     flushVitals(): void;
-    /** Stop all timers and flush remaining data. */
     dispose(): void;
     private buildIngestUrl;
-    /** Try sending via navigator.sendBeacon. Returns true if successful. */
+    private buildVitalsUrl;
+    private buildUrl;
     private trySendBeacon;
-    /** Send via fetch with keepalive and the API key header. */
     private sendFetch;
 }
-//# sourceMappingURL=transport.d.ts.map

package/dist/transport.js

@@ -1,18 +1,31 @@
 /**
- * Transport layer for the browser SDK.
+ * Browser transport.
  *
- * Two send paths:
- *   1. Errors → POST /v1/ingest/{project_id} (immediate, same wire format as sdk-node)
- *   2. Vitals → POST /v1/vitals/{project_id} (batched array)
+ * - Errors → POST /v1/ingest/{project_id} (per-event, immediate).
+ * - Vitals → POST /v1/vitals/{project_id} (batched).
  *
- * Primary transport: navigator.sendBeacon() — fire-and-forget, survives page unload.
- * Fallback: fetch() with keepalive: true.
- *
- * Vitals are buffered and flushed on:
- *   - Buffer reaching vitalsBufferSize (default: 10)
- *   - Timer tick (default: 10s)
- *   - Page visibility change to "hidden" (user leaving)
+ * Uses navigator.sendBeacon when available so requests survive page unload,
+ * falling back to `fetch({ keepalive: true })`. Vitals flush on buffer full,
+ * interval tick, and page visibilitychange/pagehide.
  */
+import { attempt, attemptAsync } from "./_vendor/result-runtime/attempt.js";
+import { getDefaultHeaders } from "./_vendor/sdk-runtime/runtime/public-sdk-runtime.js";
+const SDK_NAME = "@squasher-ai/browser";
+const SDK_VERSION = "0.3.0";
+const BEACON_CONTENT_TYPE = "text/plain";
+// One allocation per process; getDefaultHeaders is pure given package
+// metadata and platform detection memoizes inside sdk-core.
+const DEFAULT_TELEMETRY_HEADERS = getDefaultHeaders({
+    packageName: SDK_NAME,
+    packageVersion: SDK_VERSION,
+});
+function normalizeEndpoint(endpoint) {
+    const trimmed = endpoint.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    return trimmed.replace(/\/+$/, "");
+}
 export class Transport {
     config;
     vitalsBuffer = [];
@@ -20,50 +33,47 @@ export class Transport {
     disposed = false;
     constructor(config) {
         this.config = config;
-        // Start the vitals flush timer
         this.flushTimer = setInterval(() => {
             this.flushVitals();
         }, config.vitalsFlushIntervalMs);
-        // Flush vitals when the page is being hidden (user leaving/switching tabs)
-        if (typeof document !== "undefined") {
-            document.addEventListener("visibilitychange", () => {
-                if (document.visibilityState === "hidden") {
+        if (globalThis.document) {
+            globalThis.document.addEventListener("visibilitychange", () => {
+                if (globalThis.document.visibilityState === "hidden") {
                     this.flushVitals();
                 }
             });
         }
-        // Also flush on pagehide (more reliable than unload)
-        if (typeof window !== "undefined") {
-            window.addEventListener("pagehide", () => {
+        // `pagehide` fires in cases where `unload` does not (bfcache, iOS Safari).
+        if (globalThis.window) {
+            globalThis.window.addEventListener("pagehide", () => {
                 this.flushVitals();
             });
         }
     }
-    // ─── Error sending (immediate) ──────────────────────────────────────
-    /** Send a single telemetry event immediately. Fire-and-forget. */
+    /** Fire-and-forget. */
     sendEvent(event) {
         if (this.disposed)
             return;
         const url = this.buildIngestUrl();
+        const beaconUrl = this.buildIngestUrl({ beacon: true });
+        if (!url || !beaconUrl) {
+            return;
+        }
         const body = JSON.stringify(event);
-        // Try sendBeacon first (survives page unload)
-        if (this.trySendBeacon(this.buildIngestUrl({ beacon: true }), body)) {
+        if (this.trySendBeacon(beaconUrl, body)) {
             if (this.config.debug) {
                 console.log("[squasher] Error sent via sendBeacon");
             }
             return;
         }
-        // Fallback to fetch with keepalive
         this.sendFetch(url, body).catch(() => {
-            // Fire-and-forget — errors are best-effort in the browser
+            // Best-effort in the browser.
         });
     }
-    /** Backward-compatible alias for error events. */
+    /** @deprecated use {@link sendEvent}. */
     sendError(event) {
         this.sendEvent(event);
     }
-    // ─── Vitals buffering ───────────────────────────────────────────────
-    /** Buffer a vital event. Auto-flushes when buffer is full. */
     enqueueVital(event) {
         if (this.disposed)
             return;
@@ -72,25 +82,25 @@ export class Transport {
             this.flushVitals();
         }
     }
-    /** Flush all buffered vitals immediately. */
     flushVitals() {
         if (this.vitalsBuffer.length === 0)
             return;
+        const url = this.buildVitalsUrl();
+        const beaconUrl = this.buildVitalsUrl({ beacon: true });
+        if (!url || !beaconUrl) {
+            return;
+        }
         const events = this.vitalsBuffer.splice(0);
-        const url = `${this.config.endpoint}/v1/vitals/${this.config.projectId}`;
         const payload = { events };
         const body = JSON.stringify(payload);
-        if (this.trySendBeacon(url, body)) {
+        if (this.trySendBeacon(beaconUrl, body)) {
             if (this.config.debug) {
                 console.log(`[squasher] Flushed ${events.length} vitals via sendBeacon`);
             }
             return;
         }
-        this.sendFetch(url, body).catch(() => {
-            // Best-effort
-        });
+        this.sendFetch(url, body).catch(() => { });
     }
-    /** Stop all timers and flush remaining data. */
     dispose() {
         this.disposed = true;
         if (this.flushTimer) {
@@ -99,47 +109,57 @@ export class Transport {
         }
         this.flushVitals();
     }
-    // ─── Private helpers ────────────────────────────────────────────────
     buildIngestUrl(options) {
-        const baseUrl = `${this.config.endpoint}/v1/ingest/${this.config.projectId}`;
+        return this.buildUrl("ingest", options);
+    }
+    buildVitalsUrl(options) {
+        return this.buildUrl("vitals", options);
+    }
+    buildUrl(kind, options) {
+        const endpoint = normalizeEndpoint(this.config.endpoint);
+        if (!endpoint) {
+            return null;
+        }
+        const baseUrl = `${endpoint}/v1/${kind}/${this.config.projectId}`;
         if (!options?.beacon) {
             return baseUrl;
         }
         return `${baseUrl}?key=${encodeURIComponent(this.config.apiKey)}`;
     }
-    /** Try sending via navigator.sendBeacon. Returns true if successful. */
     trySendBeacon(url, body) {
-        if (typeof navigator === "undefined" || !navigator.sendBeacon) {
-            return false;
-        }
-        try {
-            const blob = new Blob([body], { type: "application/json" });
-            return navigator.sendBeacon(url, blob);
-        }
-        catch {
+        if (!globalThis.navigator?.sendBeacon) {
             return false;
         }
+        return attempt({
+            try: () => {
+                const blob = new Blob([body], { type: BEACON_CONTENT_TYPE });
+                return globalThis.navigator.sendBeacon(url, blob);
+            },
+            catch: () => false,
+        });
     }
-    /** Send via fetch with keepalive and the API key header. */
     async sendFetch(url, body) {
-        try {
-            await fetch(url, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    "x-squasher-key": this.config.apiKey,
-                },
-                body,
-                keepalive: true,
-            });
-            if (this.config.debug) {
-                console.log("[squasher] Event sent via fetch");
-            }
-        }
-        catch (err) {
-            if (this.config.debug) {
-                console.warn("[squasher] Failed to send event:", err);
-            }
-        }
+        await attemptAsync({
+            try: async () => {
+                await fetch(url, {
+                    method: "POST",
+                    headers: {
+                        ...DEFAULT_TELEMETRY_HEADERS,
+                        "Content-Type": "application/json",
+                        "x-squasher-key": this.config.apiKey,
+                    },
+                    body,
+                    keepalive: true,
+                });
+                if (this.config.debug) {
+                    console.log("[squasher] Event sent via fetch");
+                }
+            },
+            catch: ({ cause }) => {
+                if (this.config.debug) {
+                    console.warn("[squasher] Failed to send event:", cause);
+                }
+            },
+        });
     }
 }

package/dist/types.d.ts

@@ -1,16 +1,15 @@
 /**
  * @squasher-ai/browser — Type definitions for the browser SDK.
  *
- * Defines its own types to avoid runtime dependency on @squasher-ai/node or
- * @squasher-ai/api-spec. Shapes match the canonical wire protocol in
- * packages/sdk-spec/protocol.schema.json.
+ * Uses type-only telemetry contracts so the runtime stays browser-safe.
  */
+import type { AnalyticsContext, Breadcrumb as ApiBreadcrumb, IngestEvent, IngestResponse, JsonObject, Level, LlmContext, PageContext, SessionContext, StackFrame, TelemetryKind, TelemetryMeasurement, TelemetrySamplingConfig, ToolCallContext, TraceContext, UserContext, VisitorContext } from "./_vendor/telemetry-contract/sdk/public-contract.js";
 export interface BrowserConfig {
     /** API key (sq_pk_...). Required. */
     apiKey: string;
     /** Project ID (UUID). Required. */
     projectId: string;
-    /** Ingestion endpoint. Default: "https://ingest.squasher.ai" */
+    /** Public edge ingestion endpoint. Default: "https://ingest.squasher.ai" */
     endpoint?: string;
     /** Environment tag (production, staging, development). */
     environment?: string;
@@ -18,8 +17,8 @@ export interface BrowserConfig {
     release?: string;
     /** Enable debug logging to console. Default: false. */
     debug?: boolean;
-    /** Error sampling rate 0-1. Default: 1 (capture everything). */
-    sampleRate?: number;
+    /** Outcome-aware, deterministic event sampling. */
+    sampling?: TelemetrySamplingConfig;
     /** Web Vitals sampling rate 0-1. Default: 1. */
     vitalsSampleRate?: number;
     /** Enable Core Web Vitals collection. Default: true. */
@@ -28,6 +27,8 @@ export interface BrowserConfig {
     enableErrorCapture?: boolean;
     /** Enable auto-capture breadcrumbs (navigation, clicks, fetch). Default: true. */
     enableAutoBreadcrumbs?: boolean;
+    /** Capture `console.error(...)` calls as error events. Default: false. */
+    captureConsoleErrors?: boolean;
     /**
      * Hook invoked before every error event is sent.
      * Return the event (possibly modified) to send, or null to drop.
@@ -39,11 +40,11 @@ export interface BrowserConfig {
     vitalsBufferSize?: number;
     /** Vitals flush interval in ms. Default: 10000. */
     vitalsFlushIntervalMs?: number;
-    /** Optional session replay recording powered by rrweb. */
+    /** Optional session replay recording powered by rrweb. Enabled by default. */
     replay?: ReplayConfig;
 }
 export interface ReplayConfig {
-    /** Enable rrweb session replay recording for this browser session. */
+    /** Enable rrweb session replay recording for this browser session. Default: true. */
     enabled: boolean;
     /** Session-level replay sampling rate from 0-1. Default: 1. */
     sampleRate?: number;
@@ -56,7 +57,13 @@ export interface ReplayPrivacyConfig {
     /** CSS selector for elements that should render as blocked placeholders. */
     blockSelector?: string;
 }
-export type VitalMetricName = "LCP" | "CLS" | "INP" | "FCP" | "TTFB";
+/**
+ * Well-known web vital names. Includes the 5 Core Web Vitals plus the
+ * Next.js framework metrics emitted by `useReportWebVitals` from
+ * `next/web-vitals`. The wire format accepts arbitrary strings, so custom
+ * names from other frameworks pass through unchanged.
+ */
+export type VitalMetricName = "LCP" | "CLS" | "INP" | "FCP" | "TTFB" | "Next.js-hydration" | "Next.js-route-change-to-render" | "Next.js-render" | (string & {});
 export type VitalRating = "good" | "needs-improvement" | "poor";
 export type DeviceType = "mobile" | "tablet" | "desktop";
 /** Single vital measurement sent to POST /v1/vitals/{project_id}. */
@@ -90,145 +97,37 @@ export interface VitalEvent {
     device_type?: DeviceType;
     /** Document referrer. */
     referrer?: string;
+    /** Browser language, for example en-US. */
+    language?: string;
+    /** Browser time zone, for example America/Los_Angeles. */
+    timezone?: string;
+    /** URL pathname at measurement time. */
+    page_path?: string;
+    /** URL query string without the leading question mark. */
+    query_string?: string;
+    /** UTM source query parameter. */
+    utm_source?: string;
+    /** UTM medium query parameter. */
+    utm_medium?: string;
+    /** UTM campaign query parameter. */
+    utm_campaign?: string;
 }
 /** Batched payload sent to the vitals endpoint. */
 export interface VitalsPayload {
     events: VitalEvent[];
 }
-export type Level = "fatal" | "error" | "warning" | "info" | "debug";
-export type TelemetryKind = "error" | "log" | "analytics" | "identify" | "page" | "screen" | "visitor" | "agent_session" | "agent_span" | "tool_call" | "llm_generation";
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-export interface JsonObject {
-    [key: string]: JsonValue;
-}
-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;
-    cost_usd?: number;
-    latency_ms?: number;
-    status?: string;
-    input?: JsonObject;
-    output?: JsonObject;
-}
-export interface TelemetryMeasurement {
-    name: string;
-    value: number;
-    unit?: string;
-}
-export interface BrowserErrorEvent {
-    message: string;
-    type?: string;
-    stack?: string;
-    frames?: StackFrame[];
-    level?: Level;
-    tags?: Record<string, string>;
-    user?: UserContext;
+export type { AnalyticsContext, IngestResponse, JsonObject, Level, LlmContext, PageContext, SessionContext, StackFrame, TelemetryKind, TelemetryMeasurement, ToolCallContext, TraceContext, UserContext, VisitorContext, };
+export type Breadcrumb = Omit<ApiBreadcrumb, "data"> & {
+    data?: JsonObject;
+};
+export type BrowserErrorEvent = Omit<IngestEvent, "breadcrumbs" | "extra" | "request"> & {
+    breadcrumbs?: Breadcrumb[];
+    extra?: JsonObject;
     request?: {
         url: string;
         method?: string;
     };
-    sdk?: {
-        name: string;
-        version: string;
-    };
-    timestamp?: string;
-    release?: string;
-    environment?: string;
-    breadcrumbs?: Breadcrumb[];
-    extra?: Record<string, unknown>;
-    /** Session ID for correlation with Web Vitals. */
-    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[];
-}
+};
 export interface IngestBatchPayload {
     events: BrowserErrorEvent[];
 }
-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 Breadcrumb {
-    timestamp?: string;
-    category?: string;
-    message?: string;
-    level?: string;
-    data?: Record<string, unknown>;
-}
-export interface IngestResponse {
-    id: string;
-    status: string;
-    accepted?: number;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,8 +1 @@
-/**
- * @squasher-ai/browser — Type definitions for the browser SDK.
- *
- * Defines its own types to avoid runtime dependency on @squasher-ai/node or
- * @squasher-ai/api-spec. Shapes match the canonical wire protocol in
- * packages/sdk-spec/protocol.schema.json.
- */
 export {};

package/dist/vitals.d.ts

@@ -11,7 +11,15 @@
  * Each metric fires once (LCP, FCP, TTFB) or accumulates (CLS, INP).
  * Measurements are mapped to VitalEvent and queued via the transport.
  */
-import type { Transport } from "./transport";
+import { type Metric } from "web-vitals";
+import type { VitalEvent } from "./types.js";
+declare global {
+    interface Navigator {
+        connection?: {
+            effectiveType?: string;
+        };
+    }
+}
 export interface VitalsCollectorConfig {
     /** Sampling rate 0-1 for vitals. */
     sampleRate: number;
@@ -22,9 +30,53 @@ export interface VitalsCollectorConfig {
     /** Enable debug logging. */
     debug: boolean;
 }
+/**
+ * Shape accepted by external collectors that bridge into our transport
+ * (e.g. Next.js `useReportWebVitals`). Mirrors the relevant subset of the
+ * `web-vitals` Metric and Next's `NextWebVitalsMetric` so callers can pass
+ * the framework metric object through unchanged.
+ */
+export interface ExternalVitalInput {
+    name: string;
+    value: number;
+    rating?: string;
+    delta?: number;
+    navigationType?: string;
+    /** Unique identifier the underlying lib assigns to a measurement. */
+    id?: string;
+}
+/**
+ * Map an externally-sourced web vital (Next.js custom metric or otherwise)
+ * to our VitalEvent wire shape so it can be enqueued through the transport.
+ */
+export declare function mapExternalVital(metric: ExternalVitalInput, config: VitalsCollectorConfig, route?: string): VitalEvent;
+export interface VitalsCollectorHandle {
+    /**
+     * Stop forwarding metrics from the native `web-vitals` library to the
+     * transport. The library's observers cannot be unregistered, so callbacks
+     * still fire — they just no-op. Use this when an external collector (e.g.
+     * Next.js `useReportWebVitals`) takes over so we don't double-count.
+     */
+    suppress: () => void;
+}
+export interface VitalsTransport {
+    enqueueVital(event: VitalEvent): void;
+}
+export interface VitalsRuntime {
+    getSessionId(): string;
+    observeCLS(callback: (metric: Metric) => void, options: {
+        reportAllChanges: boolean;
+    }): void;
+    observeFCP(callback: (metric: Metric) => void): void;
+    observeINP(callback: (metric: Metric) => void, options: {
+        reportAllChanges: boolean;
+    }): void;
+    observeLCP(callback: (metric: Metric) => void): void;
+    observeTTFB(callback: (metric: Metric) => void): void;
+}
+export declare const defaultVitalsRuntime: VitalsRuntime;
 /**
  * Start collecting all 5 Core Web Vitals and feed them to the transport.
  * Call once during SDK initialization.
  */
-export declare function startVitalsCollection(transport: Transport, config: VitalsCollectorConfig): void;
-//# sourceMappingURL=vitals.d.ts.map
+export declare function startVitalsCollection(transport: VitalsTransport, config: VitalsCollectorConfig, runtime?: VitalsRuntime): VitalsCollectorHandle;