routeflow-browser 0.1.4 → 0.1.5

package/dist/event_tracker.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Unified event tracking for all RouteFlow browser events.
+ */
+import { Environment } from "./types";
+interface EventTrackerConfig {
+    environment: Environment;
+    allowlist: string[];
+    ingestKey?: string;
+    maxQueueSize: number;
+    flushIntervalMs: number;
+    sampleRate: number;
+    trackExternal: boolean;
+    trackBackend: boolean;
+    trackPageViews: boolean;
+}
+interface EventStats {
+    queued: number;
+    sent: number;
+    dropped: number;
+    failed: number;
+}
+/**
+ * Initialize event tracking.
+ */
+export declare function initEventTracking(config: EventTrackerConfig): void;
+/**
+ * Track a page view.
+ */
+export declare function trackPageView(route: string, referrer?: string): void;
+/**
+ * Track a backend request.
+ */
+export declare function trackBackendRequest(url: string, init: RequestInit | undefined, startTime: number, endTime: number, response: Response | null, error: Error | null, traceId: string): void;
+/**
+ * Track an external request.
+ */
+export declare function trackExternalRequest(url: string, init: RequestInit | undefined, startTime: number, endTime: number, response: Response | null, error: Error | null): void;
+/**
+ * Get event stats.
+ */
+export declare function getEventStats(): EventStats;
+/**
+ * Get queue size.
+ */
+export declare function getEventQueueSize(): number;
+/**
+ * Stop event tracking.
+ */
+export declare function stopEventTracking(): void;
+export {};

package/dist/event_tracker.js

@@ -0,0 +1,344 @@
+/**
+ * Unified event tracking for all RouteFlow browser events.
+ */
+import { extractHostname, isHostAllowed, validateTargetHost, } from "./validate";
+import { getCurrentFrontendRoute } from "./route";
+import { getOrCreateSessionId, generateTraceId } from "./trace";
+import { sendEvents } from "./client";
+class EventTracker {
+    constructor(config) {
+        this.queue = [];
+        this.stats = {
+            queued: 0,
+            sent: 0,
+            dropped: 0,
+            failed: 0,
+        };
+        this.flushTimer = null;
+        this.SDK_NAME = "@routeflow/browser";
+        this.SDK_VERSION = "0.1.5";
+        this.lastPageView = null;
+        this.config = config;
+        this.startFlushTimer();
+    }
+    /**
+     * Track a page view event.
+     */
+    trackPageView(route, referrer) {
+        if (!this.config.trackPageViews) {
+            return;
+        }
+        // Don't track duplicate page views
+        if (this.lastPageView === route) {
+            return;
+        }
+        this.lastPageView = route;
+        try {
+            // Sample rate check
+            if (Math.random() > this.config.sampleRate) {
+                return;
+            }
+            const session_id = getOrCreateSessionId();
+            const event = {
+                type: "frontend_page_view",
+                timestamp: new Date().toISOString(),
+                session_id,
+                environment: this.config.environment,
+                frontend_route: route,
+                sdk: {
+                    name: this.SDK_NAME,
+                    version: this.SDK_VERSION,
+                },
+            };
+            if (referrer) {
+                event.referrer = referrer;
+            }
+            // Add code version if available
+            if (typeof window !== "undefined" && window.__ROUTEFLOW_CODE_VERSION__) {
+                event.code_version = window.__ROUTEFLOW_CODE_VERSION__;
+            }
+            this.queueEvent(event);
+        }
+        catch {
+            // Never throw
+        }
+    }
+    /**
+     * Track a frontend-to-backend request.
+     */
+    trackBackendRequest(url, init, startTime, endTime, response, error, traceId) {
+        if (!this.config.trackBackend) {
+            return;
+        }
+        try {
+            // Sample rate check
+            if (Math.random() > this.config.sampleRate) {
+                return;
+            }
+            const method = (init?.method || "GET").toUpperCase();
+            const duration_ms = Math.round(endTime - startTime);
+            let outcome = "unknown";
+            let status_code;
+            if (error) {
+                outcome = "failure";
+            }
+            else if (response) {
+                status_code = response.status;
+                outcome = response.ok ? "success" : "failure";
+            }
+            const session_id = getOrCreateSessionId();
+            const frontend_route = getCurrentFrontendRoute();
+            const event = {
+                type: "frontend_backend_request",
+                timestamp: new Date(startTime).toISOString(),
+                trace_id: traceId,
+                session_id,
+                environment: this.config.environment,
+                frontend_route,
+                method,
+                backend_url: url,
+                duration_ms,
+                outcome,
+                sdk: {
+                    name: this.SDK_NAME,
+                    version: this.SDK_VERSION,
+                },
+            };
+            if (status_code !== undefined) {
+                event.status_code = status_code;
+            }
+            // Add code version if available
+            if (typeof window !== "undefined" && window.__ROUTEFLOW_CODE_VERSION__) {
+                event.code_version = window.__ROUTEFLOW_CODE_VERSION__;
+            }
+            this.queueEvent(event);
+        }
+        catch {
+            // Never throw
+        }
+    }
+    /**
+     * Track an external dependency request.
+     */
+    trackExternalRequest(url, init, startTime, endTime, response, error) {
+        if (!this.config.trackExternal) {
+            return;
+        }
+        try {
+            // Don't track requests to the Routeflow ingest endpoint (prevents feedback loop)
+            if (url.includes('/v1/ingest')) {
+                return;
+            }
+            // Sample rate check
+            if (Math.random() > this.config.sampleRate) {
+                return;
+            }
+            // Extract hostname
+            const hostname = extractHostname(url);
+            if (!hostname) {
+                return;
+            }
+            // Check allowlist
+            if (!isHostAllowed(hostname, this.config.allowlist)) {
+                return;
+            }
+            // Validate hostname (no scheme, path, query)
+            if (!validateTargetHost(hostname)) {
+                return;
+            }
+            const method = (init?.method || "GET").toUpperCase();
+            const duration_ms = Math.round(endTime - startTime);
+            let outcome = "unknown";
+            let status_code;
+            if (error) {
+                outcome = "failure";
+            }
+            else if (response) {
+                status_code = response.status;
+                outcome = response.ok ? "success" : "failure";
+            }
+            // Extract trace_id from request headers (same as sent to backend)
+            let trace_id;
+            const session_id = getOrCreateSessionId();
+            if (init && init.headers) {
+                const headers = new Headers(init.headers);
+                trace_id = headers.get("x-routeflow-trace-id") || undefined;
+            }
+            // Fallback: generate new trace_id if not found
+            if (!trace_id) {
+                trace_id = generateTraceId();
+            }
+            const frontend_route = getCurrentFrontendRoute();
+            const event = {
+                type: "frontend_external_request_observed",
+                timestamp: new Date(startTime).toISOString(),
+                trace_id,
+                session_id,
+                environment: this.config.environment,
+                frontend_route,
+                target_host: hostname,
+                method,
+                duration_ms,
+                outcome,
+                sdk: {
+                    name: this.SDK_NAME,
+                    version: this.SDK_VERSION,
+                },
+            };
+            if (status_code !== undefined) {
+                event.status_code = status_code;
+            }
+            // Add code version if available
+            if (typeof window !== "undefined" && window.__ROUTEFLOW_CODE_VERSION__) {
+                event.code_version = window.__ROUTEFLOW_CODE_VERSION__;
+            }
+            this.queueEvent(event);
+        }
+        catch {
+            // Never throw
+        }
+    }
+    /**
+     * Queue an event for sending.
+     */
+    queueEvent(event) {
+        if (this.queue.length >= this.config.maxQueueSize) {
+            this.stats.dropped++;
+            return;
+        }
+        this.queue.push(event);
+        this.stats.queued++;
+        // Flush if queue is getting large
+        if (this.queue.length >= 50) {
+            this.flush();
+        }
+    }
+    /**
+     * Flush queued events to backend.
+     */
+    async flush() {
+        if (this.queue.length === 0) {
+            return;
+        }
+        // Check for ingest key
+        if (!this.config.ingestKey) {
+            // Drop events silently
+            this.stats.dropped += this.queue.length;
+            this.queue = [];
+            return;
+        }
+        // Take events from queue
+        const events = this.queue.splice(0, this.queue.length);
+        // Build payload
+        const payload = {
+            sent_at: new Date().toISOString(),
+            events,
+        };
+        // Send to backend
+        const success = await sendEvents(payload, this.config.ingestKey);
+        if (success) {
+            this.stats.sent += events.length;
+        }
+        else {
+            this.stats.failed += events.length;
+        }
+    }
+    /**
+     * Start flush timer.
+     */
+    startFlushTimer() {
+        if (this.flushTimer !== null) {
+            return;
+        }
+        this.flushTimer = window.setInterval(() => {
+            this.flush();
+        }, this.config.flushIntervalMs);
+    }
+    /**
+     * Stop flush timer.
+     */
+    stop() {
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Final flush
+        this.flush();
+    }
+    /**
+     * Get current stats.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get queue size.
+     */
+    getQueueSize() {
+        return this.queue.length;
+    }
+}
+let tracker = null;
+/**
+ * Initialize event tracking.
+ */
+export function initEventTracking(config) {
+    if (tracker) {
+        tracker.stop();
+    }
+    tracker = new EventTracker(config);
+}
+/**
+ * Track a page view.
+ */
+export function trackPageView(route, referrer) {
+    if (!tracker) {
+        return;
+    }
+    tracker.trackPageView(route, referrer);
+}
+/**
+ * Track a backend request.
+ */
+export function trackBackendRequest(url, init, startTime, endTime, response, error, traceId) {
+    if (!tracker) {
+        return;
+    }
+    tracker.trackBackendRequest(url, init, startTime, endTime, response, error, traceId);
+}
+/**
+ * Track an external request.
+ */
+export function trackExternalRequest(url, init, startTime, endTime, response, error) {
+    if (!tracker) {
+        return;
+    }
+    tracker.trackExternalRequest(url, init, startTime, endTime, response, error);
+}
+/**
+ * Get event stats.
+ */
+export function getEventStats() {
+    if (!tracker) {
+        return { queued: 0, sent: 0, dropped: 0, failed: 0 };
+    }
+    return tracker.getStats();
+}
+/**
+ * Get queue size.
+ */
+export function getEventQueueSize() {
+    if (!tracker) {
+        return 0;
+    }
+    return tracker.getQueueSize();
+}
+/**
+ * Stop event tracking.
+ */
+export function stopEventTracking() {
+    if (tracker) {
+        tracker.stop();
+        tracker = null;
+    }
+}

package/dist/fetch_patch.d.ts

@@ -1,14 +1,15 @@
 /**
- * Fetch patching for correlation headers and external span tracking.
+ * Fetch patching for correlation headers and event tracking.
  *
  * This SDK patches fetch() to:
  * 1. Add correlation headers to requests to user's app backend
- * 2. Track external requests and send telemetry to RouteFlow backend
+ * 2. Track backend requests and send telemetry to RouteFlow
+ * 3. Track external requests and send telemetry to RouteFlow
  */
 /**
- * Patch window.fetch to add correlation headers and track external requests.
+ * Patch window.fetch to add correlation headers and track requests.
  */
-export declare function patchFetch(enableExternalTracking: boolean, backendUrl?: string): void;
+export declare function patchFetch(enableExternalTracking: boolean, enableBackendTracking: boolean, backendUrl?: string): void;
 /**
  * Restore original fetch.
  */

package/dist/fetch_patch.js

@@ -1,20 +1,22 @@
 /**
- * Fetch patching for correlation headers and external span tracking.
+ * Fetch patching for correlation headers and event tracking.
  *
  * This SDK patches fetch() to:
  * 1. Add correlation headers to requests to user's app backend
- * 2. Track external requests and send telemetry to RouteFlow backend
+ * 2. Track backend requests and send telemetry to RouteFlow
+ * 3. Track external requests and send telemetry to RouteFlow
  */
 import { isSameOrigin } from "./validate";
 import { getOrCreateSessionId, generateTraceId } from "./trace";
 import { getCurrentFrontendRoute } from "./route";
-import { trackExternalFetch } from "./external_spans";
+import { trackBackendRequest, trackExternalRequest } from "./event_tracker";
 const TRACE_ID_HEADER = "x-routeflow-trace-id";
 const SESSION_ID_HEADER = "x-routeflow-session-id";
 const FRONTEND_ROUTE_HEADER = "x-routeflow-frontend-route";
 let originalFetch;
 let isPatched = false;
 let trackExternal = false;
+let trackBackend = false;
 let userBackendUrl = ""; // User's app backend URL for header injection
 /**
  * Check if a URL should receive correlation headers.
@@ -39,9 +41,9 @@ function shouldInjectHeaders(url) {
     return isSameOrigin(url);
 }
 /**
- * Patch window.fetch to add correlation headers and track external requests.
+ * Patch window.fetch to add correlation headers and track requests.
  */
-export function patchFetch(enableExternalTracking, backendUrl) {
+export function patchFetch(enableExternalTracking, enableBackendTracking, backendUrl) {
     if (isPatched) {
         return;
     }
@@ -50,6 +52,7 @@ export function patchFetch(enableExternalTracking, backendUrl) {
     }
     originalFetch = window.fetch;
     trackExternal = enableExternalTracking;
+    trackBackend = enableBackendTracking;
     userBackendUrl = backendUrl || "";
     window.fetch = async function patchedFetch(input, init) {
         // Convert input to URL string
@@ -61,30 +64,41 @@ export function patchFetch(enableExternalTracking, backendUrl) {
         const shouldInject = shouldInjectHeaders(url);
         const sameOrigin = isSameOrigin(url);
         // Add correlation headers to requests going to user's app backend
+        let traceId;
         if (shouldInject) {
-            init = addCorrelationHeaders(input, init);
+            const result = addCorrelationHeaders(input, init);
+            init = result.init;
+            traceId = result.traceId;
         }
-        // Track external spans if enabled and not same-origin
-        // This sends telemetry to the RouteFlow backend
+        // Track backend requests (to user's app)
+        if (trackBackend && shouldInject && traceId) {
+            return trackAndFetchBackend(url, init, traceId);
+        }
+        // Track external requests (to third-party APIs)
         if (trackExternal && !sameOrigin) {
-            return trackAndFetch(url, init);
+            return trackAndFetchExternal(url, init);
         }
-        // Regular fetch
+        // Regular fetch (no tracking)
         return originalFetch(input, init);
     };
     isPatched = true;
 }
 /**
  * Add RouteFlow correlation headers to requests going to user's app backend.
+ * Returns the modified init and the trace ID that was added.
  */
 function addCorrelationHeaders(input, init) {
     // Get or create headers
     const headers = new Headers(init?.headers);
     // Add trace ID if not already present (unique per request)
+    let traceId;
     if (!headers.has(TRACE_ID_HEADER)) {
-        const traceId = generateTraceId();
+        traceId = generateTraceId();
         headers.set(TRACE_ID_HEADER, traceId);
     }
+    else {
+        traceId = headers.get(TRACE_ID_HEADER);
+    }
     // Add session ID if not already present (persists across requests)
     if (!headers.has(SESSION_ID_HEADER)) {
         const sessionId = getOrCreateSessionId();
@@ -96,15 +110,38 @@ function addCorrelationHeaders(input, init) {
         headers.set(FRONTEND_ROUTE_HEADER, route);
     }
     return {
-        ...init,
-        headers,
+        init: {
+            ...init,
+            headers,
+        },
+        traceId,
     };
 }
 /**
- * Track external fetch call and send telemetry to RouteFlow backend.
- * This does NOT add correlation headers - those are only for same-origin requests.
+ * Track backend request and send telemetry to RouteFlow.
+ */
+async function trackAndFetchBackend(url, init, traceId) {
+    const startTime = performance.now();
+    let response = null;
+    let error = null;
+    try {
+        response = await originalFetch(url, init);
+        return response;
+    }
+    catch (e) {
+        error = e;
+        throw e;
+    }
+    finally {
+        const endTime = performance.now();
+        // Send telemetry about this backend request
+        trackBackendRequest(url, init, startTime, endTime, response, error, traceId);
+    }
+}
+/**
+ * Track external request and send telemetry to RouteFlow.
  */
-async function trackAndFetch(url, init) {
+async function trackAndFetchExternal(url, init) {
     const startTime = performance.now();
     let response = null;
     let error = null;
@@ -118,8 +155,8 @@ async function trackAndFetch(url, init) {
     }
     finally {
         const endTime = performance.now();
-        // This sends telemetry data to RouteFlow backend
-        trackExternalFetch(url, init, startTime, endTime, response, error);
+        // Send telemetry about this external request
+        trackExternalRequest(url, init, startTime, endTime, response, error);
     }
 }
 /**

package/dist/init.js

@@ -1,10 +1,10 @@
 /**
  * Initialization and configuration for Routeflow Browser SDK.
  */
-import { initRouteTracking, getCurrentFrontendRoute } from "./route";
+import { initRouteTracking, getCurrentFrontendRoute, setRouteChangeCallback } from "./route";
 import { getOrCreateSessionId } from "./trace";
 import { patchFetch, unpatchFetch } from "./fetch_patch";
-import { initExternalSpanTracking, getExternalSpanStats, getExternalSpanQueueSize, stopExternalSpanTracking, } from "./external_spans";
+import { initEventTracking, getEventStats, getEventQueueSize, stopEventTracking, trackPageView, } from "./event_tracker";
 let isInitialized = false;
 let config = {
     ingestKey: "",
@@ -107,36 +107,47 @@ export function initRouteflow(opts) {
     }
     // Initialize route tracking
     initRouteTracking();
+    // Set up route change callback to track page views on navigation
+    setRouteChangeCallback((route) => {
+        trackPageView(route);
+    });
     // Initialize session ID (persists across page navigation within session)
     getOrCreateSessionId();
-    // Patch fetch for correlation headers (pass user's backend URL)
-    patchFetch(config.trackExternal, config.backendUrl);
-    // Initialize external span tracking if enabled
-    if (config.trackExternal) {
-        initExternalSpanTracking({
-            environment: config.environment,
-            allowlist: config.externalAllowlist,
-            ingestKey: config.ingestKey || undefined,
-            maxQueueSize: config.maxQueueSize,
-            flushIntervalMs: config.flushIntervalMs,
-            sampleRate: config.sampleRate,
-        });
-    }
+    // Patch fetch for correlation headers and tracking
+    patchFetch(config.trackExternal, // Track external API calls
+    true, // Always track backend requests
+    config.backendUrl);
+    // Initialize unified event tracking
+    initEventTracking({
+        environment: config.environment,
+        allowlist: config.externalAllowlist,
+        ingestKey: config.ingestKey || undefined,
+        maxQueueSize: config.maxQueueSize,
+        flushIntervalMs: config.flushIntervalMs,
+        sampleRate: config.sampleRate,
+        trackExternal: config.trackExternal,
+        trackBackend: true, // Always track backend requests
+        trackPageViews: true, // Always track page views
+    });
+    // Track initial page view
+    const currentRoute = getCurrentFrontendRoute();
+    const referrer = typeof document !== 'undefined' ? document.referrer : undefined;
+    trackPageView(currentRoute, referrer);
     isInitialized = true;
 }
 /**
  * Get Routeflow stats.
  */
 export function getRouteflowStats() {
-    const externalStats = getExternalSpanStats();
+    const eventStats = getEventStats();
     return {
         enabled: config.enabled,
         session_id: getOrCreateSessionId(),
         current_route: getCurrentFrontendRoute(),
-        events_queued: getExternalSpanQueueSize(),
-        events_sent: externalStats.sent,
-        events_dropped: externalStats.dropped,
-        events_failed: externalStats.failed,
+        events_queued: getEventQueueSize(),
+        events_sent: eventStats.sent,
+        events_dropped: eventStats.dropped,
+        events_failed: eventStats.failed,
         external_tracking_enabled: config.trackExternal,
         has_ingest_key: !!config.ingestKey,
     };
@@ -149,6 +160,6 @@ export function shutdownRouteflow() {
         return;
     }
     unpatchFetch();
-    stopExternalSpanTracking();
+    stopEventTracking();
     isInitialized = false;
 }

package/dist/route.d.ts

@@ -1,6 +1,10 @@
 /**
  * Frontend route tracking (framework-agnostic).
  */
+/**
+ * Set route change callback.
+ */
+export declare function setRouteChangeCallback(callback: (route: string) => void): void;
 /**
  * Initialize route tracking by patching history API.
  */

package/dist/route.js

@@ -3,6 +3,13 @@
  */
 import { normalizeFrontendRoute } from "./validate";
 let currentRoute = "/";
+let onRouteChange = null;
+/**
+ * Set route change callback.
+ */
+export function setRouteChangeCallback(callback) {
+    onRouteChange = callback;
+}
 /**
  * Initialize route tracking by patching history API.
  */
@@ -32,7 +39,14 @@ export function initRouteTracking() {
  * Update the current route from location.pathname.
  */
 function updateCurrentRoute() {
-    currentRoute = normalizeFrontendRoute(window.location.pathname);
+    const newRoute = normalizeFrontendRoute(window.location.pathname);
+    // Only trigger callback if route actually changed
+    if (newRoute !== currentRoute) {
+        currentRoute = newRoute;
+        if (onRouteChange) {
+            onRouteChange(newRoute);
+        }
+    }
 }
 /**
  * Get the current frontend route.

package/dist/types.d.ts

@@ -40,9 +40,41 @@ export interface ExternalSpanEvent {
     };
     code_version?: string;
 }
+export interface PageViewEvent {
+    type: "frontend_page_view";
+    timestamp: string;
+    session_id: string;
+    environment: Environment;
+    frontend_route: string;
+    referrer?: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    code_version?: string;
+}
+export interface BackendRequestEvent {
+    type: "frontend_backend_request";
+    timestamp: string;
+    trace_id: string;
+    session_id: string;
+    environment: Environment;
+    frontend_route: string;
+    method: string;
+    backend_url: string;
+    duration_ms: number;
+    outcome: "success" | "failure" | "unknown";
+    status_code?: number;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    code_version?: string;
+}
+export type RouteflowEvent = ExternalSpanEvent | PageViewEvent | BackendRequestEvent;
 export interface IngestPayload {
     sent_at: string;
-    events: ExternalSpanEvent[];
+    events: RouteflowEvent[];
 }
 export interface RouteflowStats {
     enabled: boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "routeflow-browser",
-  "version": "0.1.4",
-  "description": "Browser SDK for Routeflow - Frontend to backend correlation and external dependency tracking",
+  "version": "0.1.5",
+  "description": "Browser SDK for Routeflow - Frontend telemetry, correlation headers, and dependency tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {