routeflow-browser 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# @routeflow/browser
+
+Browser SDK for Routeflow - Frontend-to-backend correlation and external dependency tracking.
+
+## Installation
+
+```bash
+npm install @routeflow/browser
+```
+
+## Quick Start
+
+### Basic Setup (Correlation Only)
+
+Add correlation headers to all same-origin API calls with one line:
+
+```typescript
+import { initRouteflow } from "@routeflow/browser";
+
+initRouteflow();
+```
+
+That's it! Now all same-origin `fetch()` calls will automatically include:
+- `x-routeflow-trace-id` - Unique session ID (persisted across page navigations)
+- `x-routeflow-frontend-route` - Current frontend route (e.g., `/checkout`)
+
+## How It Works
+
+### Automatic Correlation Headers
+
+The SDK patches `window.fetch` to inject correlation headers into **same-origin requests only**:
+
+```javascript
+// Your code
+fetch("/api/orders", { method: "POST" });
+
+// SDK automatically adds headers:
+// x-routeflow-trace-id: 550e8400-e29b-41d4-a716-446655440000
+// x-routeflow-frontend-route: /checkout
+```
+
+- **Trace ID**: Generated once per browser tab session, stored in `sessionStorage`
+- **Frontend Route**: Tracks `location.pathname` (no query strings) by monitoring history API
+- **Framework agnostic**: Works with React, Vue, Next.js, vanilla JS, etc.
+- **No CORS issues**: Headers only added to same-origin requests
+
+### External Dependency Tracking (Optional)
+
+Track calls to external APIs (Stripe, S3, etc.) and correlate them with frontend behavior:
+
+```typescript
+initRouteflow({
+  ingestKey: "your-routeflow-ingest-key",
+  trackExternal: true,
+  externalAllowlist: [
+    "api.stripe.com",
+    "*.amazonaws.com",
+    "api.example.com"
+  ]
+});
+```
+
+The SDK will:
+1. Track timing and outcomes of cross-origin `fetch()` calls
+2. Send telemetry events to Routeflow backend
+3. Only track hosts in the allowlist (for privacy and performance)
+
+**Privacy guarantee**: Only the **hostname** is captured (no URLs, paths, query strings, headers, or bodies).
+
+## Configuration Options
+
+```typescript
+interface RouteflowInitOptions {
+  // Optional ingest key for sending external spans
+  ingestKey?: string;
+
+  // Enable/disable SDK (default: true)
+  enabled?: boolean;
+
+  // Environment name (default: "production")
+  environment?: "production" | "staging" | "preview" | "development";
+
+  // Sample rate for events 0.0-1.0 (default: 1.0)
+  sampleRate?: number;
+
+  // Enable tracking of external dependency calls (default: false)
+  trackExternal?: boolean;
+
+  // Allowlist of hostnames for external tracking (default: [])
+  // Supports wildcards: "*.amazonaws.com"
+  externalAllowlist?: string[];
+
+  // Flush interval in milliseconds (default: 1000)
+  flushIntervalMs?: number;
+
+  // Maximum queue size before dropping events (default: 5000)
+  maxQueueSize?: number;
+}
+```
+
+## Examples
+
+### With Environment
+
+```typescript
+initRouteflow({
+  environment: process.env.NODE_ENV === "production" ? "production" : "development"
+});
+```
+
+### With Runtime Ingest Key
+
+If you inject the key at build time or via a script tag:
+
+```html
+<script>
+  window.__ROUTEFLOW_INGEST_KEY__ = "your-ingest-key-from-server";
+</script>
+<script src="/app.js"></script>
+```
+
+```typescript
+// SDK will automatically use window.__ROUTEFLOW_INGEST_KEY__
+initRouteflow({
+  trackExternal: true,
+  externalAllowlist: ["api.stripe.com"]
+});
+```
+
+### With Code Version
+
+Track which version of your frontend code generated events:
+
+```html
+<script>
+  window.__ROUTEFLOW_CODE_VERSION__ = "abc123def"; // Git SHA
+</script>
+```
+
+### Sampling for High Traffic
+
+Only track 10% of sessions:
+
+```typescript
+initRouteflow({
+  trackExternal: true,
+  externalAllowlist: ["api.stripe.com"],
+  sampleRate: 0.1
+});
+```
+
+## Stats and Debugging
+
+Check SDK status:
+
+```typescript
+import { getRouteflowStats } from "@routeflow/browser";
+
+const stats = getRouteflowStats();
+console.log(stats);
+// {
+//   enabled: true,
+//   trace_id: "550e8400-e29b-41d4-a716-446655440000",
+//   current_route: "/checkout",
+//   events_queued: 0,
+//   events_sent: 42,
+//   events_dropped: 0,
+//   events_failed: 0,
+//   external_tracking_enabled: true,
+//   has_ingest_key: true
+// }
+```
+
+## Privacy & Security
+
+### What We Collect
+
+**For correlation (always)**:
+- Trace ID (random UUID, session-scoped)
+- Frontend route pathname (no query strings)
+
+**For external spans (opt-in)**:
+- Target hostname only (e.g., `api.stripe.com`)
+- HTTP method (e.g., `POST`)
+- Duration in milliseconds
+- Outcome (`success`, `failure`, `unknown`)
+- Status code (if available)
+
+### What We DON'T Collect
+
+- ❌ Full URLs
+- ❌ URL paths or query parameters
+- ❌ Request/response headers
+- ❌ Request/response bodies
+- ❌ Cookies
+- ❌ User IDs or personal information
+- ❌ IP addresses
+
+### CORS Considerations
+
+- Correlation headers are **only added to same-origin requests**
+- External tracking **never modifies** cross-origin requests
+- No risk of triggering CORS preflight checks
+
+## Requirements
+
+- Modern browsers with `fetch` support
+- TypeScript 5.0+ (for development)
+- No runtime dependencies
+
+## Advanced: Custom Backend URL
+
+The SDK is hardcoded to send events to:
+```
+https://routeflow-backend-production.up.railway.app/v1/ingest
+```
+
+This is intentional to simplify setup. Contact support if you need a custom backend URL.
+
+## License
+
+MIT
+# routeflow-browser

package/dist/client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP client for sending events to Routeflow backend.
+ */
+import { IngestPayload } from "./types";
+/**
+ * Send events to Routeflow backend.
+ */
+export declare function sendEvents(payload: IngestPayload, ingestKey: string): Promise<boolean>;

package/dist/client.js

@@ -0,0 +1,32 @@
+/**
+ * HTTP client for sending events to Routeflow backend.
+ */
+// Use localhost for development, production URL for deployed environments
+const BACKEND_URL = window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1"
+    ? "http://127.0.0.1:5004"
+    : "https://routeflow-backend-production.up.railway.app";
+const INGEST_ENDPOINT = "/v1/ingest";
+/**
+ * Send events to Routeflow backend.
+ */
+export async function sendEvents(payload, ingestKey) {
+    try {
+        const url = `${BACKEND_URL}${INGEST_ENDPOINT}`;
+        const body = JSON.stringify(payload);
+        // Use fetch with keepalive for best reliability
+        const success = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${ingestKey}`,
+                "Content-Type": "application/json",
+            },
+            body: body,
+            keepalive: true,
+        }).then((res) => res.ok, () => false);
+        return success;
+    }
+    catch (error) {
+        // Never throw - just return failure
+        return false;
+    }
+}

package/dist/external_spans.d.ts

@@ -0,0 +1,39 @@
+/**
+ * External dependency span tracking.
+ */
+import { Environment } from "./types";
+interface ExternalSpanConfig {
+    environment: Environment;
+    allowlist: string[];
+    ingestKey?: string;
+    maxQueueSize: number;
+    flushIntervalMs: number;
+    sampleRate: number;
+}
+interface SpanStats {
+    queued: number;
+    sent: number;
+    dropped: number;
+    failed: number;
+}
+/**
+ * Initialize external span tracking.
+ */
+export declare function initExternalSpanTracking(config: ExternalSpanConfig): void;
+/**
+ * Track an external fetch call.
+ */
+export declare function trackExternalFetch(url: string, init: RequestInit | undefined, startTime: number, endTime: number, response: Response | null, error: Error | null): void;
+/**
+ * Get external span stats.
+ */
+export declare function getExternalSpanStats(): SpanStats;
+/**
+ * Get queue size.
+ */
+export declare function getExternalSpanQueueSize(): number;
+/**
+ * Stop external span tracking.
+ */
+export declare function stopExternalSpanTracking(): void;
+export {};

package/dist/external_spans.js

@@ -0,0 +1,233 @@
+/**
+ * External dependency span tracking.
+ */
+import { extractHostname, isHostAllowed, validateTargetHost, } from "./validate";
+import { getCurrentFrontendRoute } from "./route";
+import { getOrCreateSessionId, generateTraceId } from "./trace";
+import { sendEvents } from "./client";
+class ExternalSpanTracker {
+    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.0"; // TODO: sync with package.json
+        this.config = config;
+        this.startFlushTimer();
+    }
+    /**
+     * Track an external fetch call.
+     */
+    trackFetch(url, init, startTime, endTime, response, error) {
+        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;
+            }
+            // Determine method
+            const method = (init?.method || "GET").toUpperCase();
+            // Calculate duration
+            const duration_ms = Math.round(endTime - startTime);
+            // Determine outcome and status code
+            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 (it was added by addCorrelationHeaders)
+            // This ensures the frontend span has the same trace_id as the backend received
+            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 (shouldn't happen)
+            if (!trace_id) {
+                trace_id = generateTraceId();
+            }
+            const frontend_route = getCurrentFrontendRoute();
+            // Build event
+            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,
+                },
+            };
+            // Add optional fields
+            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__;
+            }
+            // Queue event
+            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 external span tracking.
+ */
+export function initExternalSpanTracking(config) {
+    if (tracker) {
+        tracker.stop();
+    }
+    tracker = new ExternalSpanTracker(config);
+}
+/**
+ * Track an external fetch call.
+ */
+export function trackExternalFetch(url, init, startTime, endTime, response, error) {
+    if (!tracker) {
+        return;
+    }
+    tracker.trackFetch(url, init, startTime, endTime, response, error);
+}
+/**
+ * Get external span stats.
+ */
+export function getExternalSpanStats() {
+    if (!tracker) {
+        return { queued: 0, sent: 0, dropped: 0, failed: 0 };
+    }
+    return tracker.getStats();
+}
+/**
+ * Get queue size.
+ */
+export function getExternalSpanQueueSize() {
+    if (!tracker) {
+        return 0;
+    }
+    return tracker.getQueueSize();
+}
+/**
+ * Stop external span tracking.
+ */
+export function stopExternalSpanTracking() {
+    if (tracker) {
+        tracker.stop();
+        tracker = null;
+    }
+}

package/dist/fetch_patch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fetch patching for correlation headers and external span tracking.
+ */
+/**
+ * Patch window.fetch to add correlation headers.
+ */
+export declare function patchFetch(enableExternalTracking: boolean): void;
+/**
+ * Restore original fetch.
+ */
+export declare function unpatchFetch(): void;

package/dist/fetch_patch.js

@@ -0,0 +1,109 @@
+/**
+ * Fetch patching for correlation headers and external span tracking.
+ */
+import { isSameOrigin } from "./validate";
+import { getOrCreateSessionId, generateTraceId } from "./trace";
+import { getCurrentFrontendRoute } from "./route";
+import { trackExternalFetch } from "./external_spans";
+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;
+/**
+ * Patch window.fetch to add correlation headers.
+ */
+export function patchFetch(enableExternalTracking) {
+    if (isPatched) {
+        return;
+    }
+    if (typeof window === "undefined" || typeof window.fetch !== "function") {
+        return;
+    }
+    originalFetch = window.fetch;
+    trackExternal = enableExternalTracking;
+    window.fetch = async function patchedFetch(input, init) {
+        // Convert input to URL string
+        const url = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        const sameOrigin = isSameOrigin(url);
+        // Add correlation headers for same-origin requests
+        // For external requests, we'll add headers in trackAndFetch if tracking is enabled
+        if (sameOrigin) {
+            init = addCorrelationHeaders(input, init);
+        }
+        // Track external spans if enabled (will also add correlation headers)
+        if (trackExternal && !sameOrigin) {
+            return trackAndFetch(url, init);
+        }
+        // Regular fetch
+        return originalFetch(input, init);
+    };
+    isPatched = true;
+}
+/**
+ * Add correlation headers to same-origin requests.
+ */
+function addCorrelationHeaders(input, init) {
+    // Get or create headers
+    const headers = new Headers(init?.headers);
+    // Add trace ID if not already present (unique per request)
+    if (!headers.has(TRACE_ID_HEADER)) {
+        const traceId = generateTraceId();
+        headers.set(TRACE_ID_HEADER, traceId);
+    }
+    // Add session ID if not already present (persists across requests)
+    if (!headers.has(SESSION_ID_HEADER)) {
+        const sessionId = getOrCreateSessionId();
+        headers.set(SESSION_ID_HEADER, sessionId);
+    }
+    // Add frontend route if not already present
+    if (!headers.has(FRONTEND_ROUTE_HEADER)) {
+        const route = getCurrentFrontendRoute();
+        headers.set(FRONTEND_ROUTE_HEADER, route);
+    }
+    return {
+        ...init,
+        headers,
+    };
+}
+/**
+ * Track external fetch call and execute it.
+ * Also adds correlation headers to tracked external requests.
+ */
+async function trackAndFetch(url, init) {
+    const startTime = performance.now();
+    let response = null;
+    let error = null;
+    // Add correlation headers to tracked external requests
+    // This allows backends in your infrastructure to correlate requests
+    init = addCorrelationHeaders(url, init);
+    try {
+        response = await originalFetch(url, init);
+        return response;
+    }
+    catch (e) {
+        error = e;
+        throw e;
+    }
+    finally {
+        const endTime = performance.now();
+        trackExternalFetch(url, init, startTime, endTime, response, error);
+    }
+}
+/**
+ * Restore original fetch.
+ */
+export function unpatchFetch() {
+    if (!isPatched) {
+        return;
+    }
+    if (typeof window !== "undefined" && originalFetch) {
+        window.fetch = originalFetch;
+    }
+    isPatched = false;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Routeflow Browser SDK
+ *
+ * Frontend-to-backend correlation and external dependency tracking.
+ */
+export { initRouteflow, getRouteflowStats } from "./init";
+export type { RouteflowInitOptions, RouteflowStats } from "./types";

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * Routeflow Browser SDK
+ *
+ * Frontend-to-backend correlation and external dependency tracking.
+ */
+export { initRouteflow, getRouteflowStats } from "./init";

package/dist/init.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Initialization and configuration for Routeflow Browser SDK.
+ */
+import { RouteflowInitOptions, RouteflowStats } from "./types";
+/**
+ * Initialize Routeflow Browser SDK.
+ */
+export declare function initRouteflow(opts?: RouteflowInitOptions): void;
+/**
+ * Get Routeflow stats.
+ */
+export declare function getRouteflowStats(): RouteflowStats;
+/**
+ * Shutdown Routeflow (for cleanup).
+ */
+export declare function shutdownRouteflow(): void;

package/dist/init.js

@@ -0,0 +1,152 @@
+/**
+ * Initialization and configuration for Routeflow Browser SDK.
+ */
+import { initRouteTracking, getCurrentFrontendRoute } from "./route";
+import { getOrCreateSessionId } from "./trace";
+import { patchFetch, unpatchFetch } from "./fetch_patch";
+import { initExternalSpanTracking, getExternalSpanStats, getExternalSpanQueueSize, stopExternalSpanTracking, } from "./external_spans";
+let isInitialized = false;
+let config = {
+    ingestKey: "",
+    enabled: true,
+    environment: "production",
+    sampleRate: 1.0,
+    trackExternal: false,
+    externalAllowlist: [],
+    flushIntervalMs: 1000,
+    maxQueueSize: 5000,
+};
+/**
+ * Detect environment from deployment platform environment variables.
+ * Supports Vercel, Netlify, CloudFlare Pages, and other common platforms.
+ */
+function detectFrontendEnvironment() {
+    if (typeof process === "undefined" || !process.env) {
+        return null;
+    }
+    // Vercel
+    // VERCEL_ENV: "production" | "preview" | "development"
+    if (process.env.VERCEL_ENV) {
+        const vercelEnv = process.env.VERCEL_ENV;
+        if (vercelEnv === "production" || vercelEnv === "preview" || vercelEnv === "development") {
+            return vercelEnv;
+        }
+        // Map "staging" if custom
+        if (vercelEnv === "staging")
+            return "staging";
+    }
+    // Netlify
+    // CONTEXT: "production" | "deploy-preview" | "branch-deploy" | "dev"
+    if (process.env.CONTEXT) {
+        const netlifyContext = process.env.CONTEXT;
+        if (netlifyContext === "production")
+            return "production";
+        if (netlifyContext === "deploy-preview")
+            return "preview";
+        if (netlifyContext === "branch-deploy")
+            return "staging";
+        if (netlifyContext === "dev")
+            return "development";
+    }
+    // Cloudflare Pages
+    // CF_PAGES_BRANCH: "main" or other branch names
+    if (process.env.CF_PAGES && process.env.CF_PAGES_BRANCH) {
+        const branch = process.env.CF_PAGES_BRANCH;
+        if (branch === "main" || branch === "master")
+            return "production";
+        if (branch.includes("staging"))
+            return "staging";
+        return "preview";
+    }
+    // AWS Amplify
+    if (process.env.AWS_BRANCH) {
+        const branch = process.env.AWS_BRANCH;
+        if (branch === "main" || branch === "master")
+            return "production";
+        if (branch.includes("staging"))
+            return "staging";
+        return "preview";
+    }
+    // Generic NODE_ENV fallback
+    if (process.env.NODE_ENV === "production")
+        return "production";
+    if (process.env.NODE_ENV === "development")
+        return "development";
+    return null;
+}
+/**
+ * Initialize Routeflow Browser SDK.
+ */
+export function initRouteflow(opts) {
+    if (isInitialized) {
+        console.warn("Routeflow already initialized");
+        return;
+    }
+    // Detect environment from deployment platform
+    const detectedEnvironment = detectFrontendEnvironment();
+    // Merge options with defaults
+    config = {
+        ingestKey: opts?.ingestKey || "",
+        enabled: opts?.enabled ?? true,
+        environment: opts?.environment || detectedEnvironment || "production",
+        sampleRate: opts?.sampleRate ?? 1.0,
+        trackExternal: opts?.trackExternal ?? false,
+        externalAllowlist: opts?.externalAllowlist || [],
+        flushIntervalMs: opts?.flushIntervalMs ?? 1000,
+        maxQueueSize: opts?.maxQueueSize ?? 5000,
+    };
+    // Try to get ingest key from window if not provided
+    if (!config.ingestKey && typeof window !== "undefined") {
+        config.ingestKey = window.__ROUTEFLOW_INGEST_KEY__ || "";
+    }
+    // If disabled, skip initialization
+    if (!config.enabled) {
+        return;
+    }
+    // Initialize route tracking
+    initRouteTracking();
+    // Initialize session ID (persists across page navigation within session)
+    getOrCreateSessionId();
+    // Patch fetch for correlation headers
+    patchFetch(config.trackExternal);
+    // 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,
+        });
+    }
+    isInitialized = true;
+}
+/**
+ * Get Routeflow stats.
+ */
+export function getRouteflowStats() {
+    const externalStats = getExternalSpanStats();
+    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,
+        external_tracking_enabled: config.trackExternal,
+        has_ingest_key: !!config.ingestKey,
+    };
+}
+/**
+ * Shutdown Routeflow (for cleanup).
+ */
+export function shutdownRouteflow() {
+    if (!isInitialized) {
+        return;
+    }
+    unpatchFetch();
+    stopExternalSpanTracking();
+    isInitialized = false;
+}

package/dist/route.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Frontend route tracking (framework-agnostic).
+ */
+/**
+ * Initialize route tracking by patching history API.
+ */
+export declare function initRouteTracking(): void;
+/**
+ * Get the current frontend route.
+ */
+export declare function getCurrentFrontendRoute(): string;

package/dist/route.js

@@ -0,0 +1,42 @@
+/**
+ * Frontend route tracking (framework-agnostic).
+ */
+import { normalizeFrontendRoute } from "./validate";
+let currentRoute = "/";
+/**
+ * Initialize route tracking by patching history API.
+ */
+export function initRouteTracking() {
+    // Set initial route
+    updateCurrentRoute();
+    // Patch pushState
+    const originalPushState = history.pushState;
+    history.pushState = function (...args) {
+        const result = originalPushState.apply(this, args);
+        updateCurrentRoute();
+        return result;
+    };
+    // Patch replaceState
+    const originalReplaceState = history.replaceState;
+    history.replaceState = function (...args) {
+        const result = originalReplaceState.apply(this, args);
+        updateCurrentRoute();
+        return result;
+    };
+    // Listen to popstate (back/forward buttons)
+    window.addEventListener("popstate", () => {
+        updateCurrentRoute();
+    });
+}
+/**
+ * Update the current route from location.pathname.
+ */
+function updateCurrentRoute() {
+    currentRoute = normalizeFrontendRoute(window.location.pathname);
+}
+/**
+ * Get the current frontend route.
+ */
+export function getCurrentFrontendRoute() {
+    return currentRoute;
+}

package/dist/trace.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Trace ID and Session ID management for browser sessions.
+ */
+/**
+ * Get or create session ID for this browser session.
+ * Session ID persists across requests within the same session.
+ */
+export declare function getOrCreateSessionId(): string;
+/**
+ * Generate a unique trace ID for a single request.
+ * Trace ID is unique per request, not persisted.
+ */
+export declare function generateTraceId(): string;
+/**
+ * Get current session ID (without creating).
+ */
+export declare function getSessionId(): string | null;

package/dist/trace.js

@@ -0,0 +1,58 @@
+/**
+ * Trace ID and Session ID management for browser sessions.
+ */
+const SESSION_ID_KEY = "routeflow_session_id";
+/**
+ * Generate a UUID v4.
+ */
+function generateUUID() {
+    // Use crypto.randomUUID if available (modern browsers)
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback: simple UUID v4 implementation
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Get or create session ID for this browser session.
+ * Session ID persists across requests within the same session.
+ */
+export function getOrCreateSessionId() {
+    try {
+        // Try to get existing session ID from sessionStorage
+        const existing = sessionStorage.getItem(SESSION_ID_KEY);
+        if (existing) {
+            return existing;
+        }
+        // Generate new session ID
+        const sessionId = generateUUID();
+        sessionStorage.setItem(SESSION_ID_KEY, sessionId);
+        return sessionId;
+    }
+    catch {
+        // If sessionStorage fails, generate ephemeral ID
+        return generateUUID();
+    }
+}
+/**
+ * Generate a unique trace ID for a single request.
+ * Trace ID is unique per request, not persisted.
+ */
+export function generateTraceId() {
+    return generateUUID();
+}
+/**
+ * Get current session ID (without creating).
+ */
+export function getSessionId() {
+    try {
+        return sessionStorage.getItem(SESSION_ID_KEY);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Type definitions for Routeflow Browser SDK.
+ */
+export type Environment = "production" | "staging" | "preview" | "development";
+export interface RouteflowInitOptions {
+    /** Optional ingest key for sending external spans to backend */
+    ingestKey?: string;
+    /** Enable/disable SDK (default: true) */
+    enabled?: boolean;
+    /** Environment name (default: "production") */
+    environment?: Environment;
+    /** Sample rate for events 0.0-1.0 (default: 1.0) */
+    sampleRate?: number;
+    /** Enable tracking of external dependency calls (default: false) */
+    trackExternal?: boolean;
+    /** Allowlist of hostnames for external tracking (default: []) */
+    externalAllowlist?: string[];
+    /** Flush interval in milliseconds (default: 1000) */
+    flushIntervalMs?: number;
+    /** Maximum queue size before dropping events (default: 5000) */
+    maxQueueSize?: number;
+}
+export interface ExternalSpanEvent {
+    type: "frontend_external_request_observed";
+    timestamp: string;
+    trace_id: string;
+    session_id: string;
+    environment: Environment;
+    frontend_route: string;
+    target_host: string;
+    method: string;
+    duration_ms: number;
+    outcome: "success" | "failure" | "unknown";
+    status_code?: number;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    code_version?: string;
+}
+export interface IngestPayload {
+    sent_at: string;
+    events: ExternalSpanEvent[];
+}
+export interface RouteflowStats {
+    enabled: boolean;
+    session_id: string;
+    current_route: string;
+    events_queued: number;
+    events_sent: number;
+    events_dropped: number;
+    events_failed: number;
+    external_tracking_enabled: boolean;
+    has_ingest_key: boolean;
+}
+declare global {
+    interface Window {
+        __ROUTEFLOW_INGEST_KEY__?: string;
+        __ROUTEFLOW_CODE_VERSION__?: string;
+    }
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Routeflow Browser SDK.
+ */
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Validation utilities for Routeflow Browser SDK.
+ */
+/**
+ * Validate that a target_host is just a hostname (no scheme, path, query).
+ */
+export declare function validateTargetHost(host: string): boolean;
+/**
+ * Check if a hostname matches an allowlist entry.
+ * Supports exact match and simple wildcard (*.example.com).
+ */
+export declare function isHostAllowed(host: string, allowlist: string[]): boolean;
+/**
+ * Normalize frontend route (remove query strings and fragments).
+ */
+export declare function normalizeFrontendRoute(path: string): string;
+/**
+ * Extract hostname from a URL string.
+ */
+export declare function extractHostname(url: string): string | null;
+/**
+ * Check if a URL is same-origin.
+ */
+export declare function isSameOrigin(url: string): boolean;

package/dist/validate.js

@@ -0,0 +1,88 @@
+/**
+ * Validation utilities for Routeflow Browser SDK.
+ */
+/**
+ * Validate that a target_host is just a hostname (no scheme, path, query).
+ */
+export function validateTargetHost(host) {
+    if (!host || typeof host !== "string") {
+        return false;
+    }
+    // Reject URLs with scheme
+    if (host.includes("://")) {
+        return false;
+    }
+    // Reject paths
+    if (host.includes("/")) {
+        return false;
+    }
+    // Reject query strings
+    if (host.includes("?")) {
+        return false;
+    }
+    // Reject fragments
+    if (host.includes("#")) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if a hostname matches an allowlist entry.
+ * Supports exact match and simple wildcard (*.example.com).
+ */
+export function isHostAllowed(host, allowlist) {
+    if (!host || allowlist.length === 0) {
+        return false;
+    }
+    for (const pattern of allowlist) {
+        // Exact match
+        if (pattern === host) {
+            return true;
+        }
+        // Wildcard match (*.example.com)
+        if (pattern.startsWith("*.")) {
+            const suffix = pattern.slice(1); // Remove the *
+            if (host.endsWith(suffix) || host === suffix.slice(1)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Normalize frontend route (remove query strings and fragments).
+ */
+export function normalizeFrontendRoute(path) {
+    if (!path) {
+        return "/";
+    }
+    // Remove query string
+    const withoutQuery = path.split("?")[0];
+    // Remove fragment
+    const withoutFragment = withoutQuery.split("#")[0];
+    return withoutFragment || "/";
+}
+/**
+ * Extract hostname from a URL string.
+ */
+export function extractHostname(url) {
+    try {
+        const urlObj = new URL(url);
+        return urlObj.hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a URL is same-origin.
+ */
+export function isSameOrigin(url) {
+    try {
+        const urlObj = new URL(url, window.location.href);
+        return urlObj.origin === window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "routeflow-browser",
+  "version": "0.1.0",
+  "description": "Browser SDK for Routeflow - Frontend to backend correlation and external dependency tracking",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublish": "npm run build"
+  },
+  "keywords": [
+    "routeflow",
+    "tracing",
+    "observability",
+    "frontend",
+    "correlation"
+  ],
+  "author": "Routeflow",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}