kodo-sdk 0.4.0

package/dist/browser.js

@@ -0,0 +1,766 @@
+/**
+ * Kodo Browser SDK
+ * Client-side error tracking, structured logging, distributed tracing, and performance monitoring
+ *
+ * Features:
+ * - Automatic error capture (window.onerror, unhandledrejection)
+ * - Breadcrumb tracking (console, clicks, navigation, XHR, fetch)
+ * - Structured logging with levels and context
+ * - Distributed tracing with spans
+ * - Web Vitals (LCP, FID, CLS)
+ * - User context
+ * - Ad-blocker bypass (tunneling)
+ */
+// =============================================================================
+// Trace class for distributed tracing
+// =============================================================================
+class Trace {
+    constructor(name, options) {
+        this._spans = [];
+        this._currentSpanId = null;
+        this._status = 'ok';
+        this._tags = {};
+        this._traceId = generateTraceId();
+        this._name = name;
+        this._op = options?.op || 'custom';
+        this._startTime = Date.now();
+        this._tags = options?.tags || {};
+    }
+    get traceId() {
+        return this._traceId;
+    }
+    /** Start a child span */
+    startSpan(name, options) {
+        const spanId = generateSpanId();
+        const span = new Span(this, spanId, this._currentSpanId, name, options?.kind || 'internal', options?.attributes);
+        this._currentSpanId = spanId;
+        return span;
+    }
+    /** Set HTTP details for the trace */
+    setHttpDetails(method, url, statusCode) {
+        this._httpMethod = method;
+        this._httpUrl = url;
+        this._httpStatusCode = statusCode;
+    }
+    /** Add a tag to the trace */
+    setTag(key, value) {
+        this._tags[key] = value;
+    }
+    /** Mark trace as error */
+    setError() {
+        this._status = 'error';
+    }
+    /** Internal: Add completed span */
+    _addSpan(span) {
+        this._spans.push(span);
+        // Reset current span to parent
+        this._currentSpanId = span.parent_span_id;
+    }
+    /** Finish the trace and send it */
+    finish() {
+        const endTime = Date.now();
+        const event = {
+            type: 'trace',
+            timestamp: this._startTime,
+            session_id: _sessionId,
+            url: window.location.href,
+            user_agent: navigator.userAgent,
+            service: _config?.service || null,
+            release: _config?.release || null,
+            environment: _config?.environment || detectEnvironment(),
+            data: {
+                trace_id: this._traceId,
+                name: this._name,
+                op: this._op,
+                start_time: this._startTime,
+                end_time: endTime,
+                status: this._status,
+                tags: this._tags,
+                http_method: this._httpMethod,
+                http_url: this._httpUrl,
+                http_status_code: this._httpStatusCode,
+                spans: this._spans,
+            },
+        };
+        queueEvent(event);
+        _log('Trace finished', { traceId: this._traceId, spans: this._spans.length });
+    }
+}
+class Span {
+    constructor(trace, spanId, parentSpanId, name, kind, attributes) {
+        this._events = [];
+        this._status = 'ok';
+        this._finished = false;
+        this._trace = trace;
+        this._spanId = spanId;
+        this._parentSpanId = parentSpanId;
+        this._name = name;
+        this._kind = kind;
+        this._startTime = Date.now();
+        this._attributes = attributes || {};
+    }
+    get spanId() {
+        return this._spanId;
+    }
+    /** Set attributes on the span */
+    setAttributes(attrs) {
+        Object.assign(this._attributes, attrs);
+    }
+    /** Add an event to the span */
+    addEvent(name, attributes) {
+        this._events.push({
+            name,
+            timestamp: Date.now(),
+            attributes,
+        });
+    }
+    /** Mark span as error */
+    setError() {
+        this._status = 'error';
+    }
+    /** Finish the span */
+    finish(options) {
+        if (this._finished)
+            return;
+        this._finished = true;
+        if (options?.status) {
+            this._status = options.status;
+        }
+        const spanData = {
+            span_id: this._spanId,
+            parent_span_id: this._parentSpanId,
+            name: this._name,
+            kind: this._kind,
+            start_time: this._startTime,
+            end_time: Date.now(),
+            status: this._status,
+            attributes: this._attributes,
+            events: this._events,
+        };
+        this._trace._addSpan(spanData);
+    }
+}
+// =============================================================================
+// Global state
+// =============================================================================
+let _config = null;
+let _sessionId = null;
+let _breadcrumbs = [];
+let _user = null;
+let _eventQueue = [];
+let _flushTimer = null;
+let _initialized = false;
+// =============================================================================
+// Main API
+// =============================================================================
+/**
+ * Initialize the Kodo SDK
+ *
+ * @example
+ * ```typescript
+ * import Kodo from 'kodo-sdk/browser';
+ *
+ * Kodo.init({
+ *   dsn: 'bpk_your_key_here',
+ *   service: 'my-app',
+ *   release: '1.0.0',
+ * });
+ * ```
+ */
+function init(config) {
+    if (_initialized) {
+        console.warn('[Kodo] Already initialized');
+        return;
+    }
+    _config = {
+        baseUrl: 'https://kodostatus.com',
+        enableBreadcrumbs: true,
+        maxBreadcrumbs: 100,
+        debug: false,
+        ...config,
+    };
+    _sessionId = generateSessionId();
+    _initialized = true;
+    setupGlobalHandlers();
+    if (_config.enableBreadcrumbs) {
+        setupBreadcrumbCapture();
+    }
+    captureWebVitals();
+    _log('Initialized', { sessionId: _sessionId });
+}
+/**
+ * Set user context for all events
+ *
+ * @example
+ * ```typescript
+ * Kodo.setUser({ id: 'user123', email: 'user@example.com' });
+ * ```
+ */
+function setUser(user) {
+    _user = user;
+    _log('User set', user);
+}
+/**
+ * Add a breadcrumb manually
+ *
+ * @example
+ * ```typescript
+ * Kodo.addBreadcrumb({
+ *   category: 'user',
+ *   message: 'Clicked checkout button',
+ *   level: 'info',
+ * });
+ * ```
+ */
+function addBreadcrumb(breadcrumb) {
+    if (!_config?.enableBreadcrumbs)
+        return;
+    const bc = {
+        ...breadcrumb,
+        timestamp: Date.now(),
+    };
+    _breadcrumbs.push(bc);
+    if (_breadcrumbs.length > (_config?.maxBreadcrumbs || 100)) {
+        _breadcrumbs = _breadcrumbs.slice(-(_config?.maxBreadcrumbs || 100));
+    }
+    _log('Breadcrumb added', bc);
+}
+/**
+ * Capture an exception manually
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   riskyOperation();
+ * } catch (error) {
+ *   Kodo.captureException(error);
+ * }
+ * ```
+ */
+function captureException(error, context) {
+    if (!_config || !_sessionId) {
+        console.warn('[Kodo] Not initialized');
+        return;
+    }
+    const event = createErrorEvent(error, context);
+    queueEvent(event);
+}
+/**
+ * Send a structured log message
+ *
+ * @example
+ * ```typescript
+ * Kodo.log('info', 'User signed in', {
+ *   logger: 'auth',
+ *   context: { userId: '123', method: 'oauth' }
+ * });
+ * ```
+ */
+function log(level, message, options) {
+    if (!_config || !_sessionId)
+        return;
+    const event = {
+        type: 'log',
+        timestamp: Date.now(),
+        session_id: _sessionId,
+        url: window.location.href,
+        user_agent: navigator.userAgent,
+        service: _config.service || null,
+        release: _config.release || null,
+        environment: _config.environment || detectEnvironment(),
+        data: {
+            level,
+            message,
+            logger: options?.logger,
+            context: options?.context,
+            stack: options?.stack,
+            trace_id: options?.traceId,
+            span_id: options?.spanId,
+        },
+    };
+    queueEvent(event);
+}
+// Convenience log methods
+const debug = (message, options) => log('debug', message, options);
+const info = (message, options) => log('info', message, options);
+const warn = (message, options) => log('warn', message, options);
+const error = (message, options) => log('error', message, options);
+const fatal = (message, options) => log('fatal', message, options);
+/**
+ * Start a distributed trace
+ *
+ * @example
+ * ```typescript
+ * const trace = Kodo.startTrace('checkout-flow', { op: 'user.action' });
+ *
+ * const fetchSpan = trace.startSpan('fetch-cart', { kind: 'client' });
+ * await fetchCart();
+ * fetchSpan.finish();
+ *
+ * trace.finish();
+ * ```
+ */
+function startTrace(name, options) {
+    return new Trace(name, options);
+}
+/**
+ * Wrap an async function with tracing
+ *
+ * @example
+ * ```typescript
+ * const result = await Kodo.trace('api-call', async (span) => {
+ *   span.setAttributes({ endpoint: '/api/orders' });
+ *   const response = await fetch('/api/orders');
+ *   span.setAttributes({ status: response.status });
+ *   return response.json();
+ * });
+ * ```
+ */
+async function trace(name, fn, options) {
+    const traceObj = startTrace(name, { op: options?.op || 'function' });
+    const span = traceObj.startSpan(name, { kind: 'internal' });
+    try {
+        const result = await fn(span);
+        span.finish({ status: 'ok' });
+        traceObj.finish();
+        return result;
+    }
+    catch (err) {
+        span.setError();
+        span.finish({ status: 'error' });
+        traceObj.setError();
+        traceObj.finish();
+        throw err;
+    }
+}
+/**
+ * Flush all pending events immediately
+ */
+async function flush() {
+    if (_eventQueue.length === 0)
+        return;
+    const events = [..._eventQueue];
+    _eventQueue = [];
+    await sendEvents(events);
+}
+// =============================================================================
+// Internal functions
+// =============================================================================
+function generateSessionId() {
+    return 'sess_' + '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);
+    });
+}
+function generateTraceId() {
+    return 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'.replace(/x/g, () => {
+        return Math.floor(Math.random() * 16).toString(16);
+    });
+}
+function generateSpanId() {
+    return 'xxxxxxxxxxxxxxxx'.replace(/x/g, () => {
+        return Math.floor(Math.random() * 16).toString(16);
+    });
+}
+function detectEnvironment() {
+    const hostname = window.location.hostname;
+    if (hostname === 'localhost' || hostname === '127.0.0.1') {
+        return 'development';
+    }
+    if (hostname.includes('staging') || hostname.includes('preview') || hostname.includes('dev.')) {
+        return 'staging';
+    }
+    return 'production';
+}
+function _log(...args) {
+    if (_config?.debug) {
+        console.log('[Kodo]', ...args);
+    }
+}
+function createErrorEvent(err, extraContext) {
+    const stack = err.stack || '';
+    const stackLines = stack.split('\n').slice(1);
+    let file;
+    let line;
+    let col;
+    const frameMatch = stackLines[0]?.match(/at\s+(?:\S+\s+)?\(?(.+):(\d+):(\d+)\)?/);
+    if (frameMatch) {
+        file = frameMatch[1];
+        line = parseInt(frameMatch[2], 10);
+        col = parseInt(frameMatch[3], 10);
+    }
+    return {
+        type: 'error',
+        timestamp: Date.now(),
+        session_id: _sessionId,
+        url: window.location.href,
+        user_agent: navigator.userAgent,
+        service: _config?.service || null,
+        release: _config?.release || null,
+        environment: _config?.environment || detectEnvironment(),
+        context: getBrowserContext(),
+        data: {
+            type: err.name,
+            message: err.message,
+            source: file,
+            lineno: line,
+            colno: col,
+            stack: stack.substring(0, 2000),
+            ...extraContext,
+        },
+    };
+}
+function queueEvent(event) {
+    if (_config?.beforeSend) {
+        const modified = _config.beforeSend(event);
+        if (modified === null) {
+            _log('Event dropped by beforeSend');
+            return;
+        }
+        event = modified;
+    }
+    _eventQueue.push(event);
+    scheduleFlush();
+}
+function scheduleFlush() {
+    if (_flushTimer)
+        return;
+    _flushTimer = setTimeout(() => {
+        _flushTimer = null;
+        flush().catch(console.error);
+    }, 2000);
+}
+async function sendEvents(events) {
+    if (!_config || events.length === 0)
+        return;
+    const payload = {
+        key: _config.dsn,
+        events,
+        breadcrumbs: _breadcrumbs.slice(-50),
+        user: _user,
+    };
+    const endpoint = _config.tunnel
+        ? `${window.location.origin}${_config.tunnel}`
+        : `${_config.baseUrl}/api/beacon`;
+    try {
+        if (document.visibilityState === 'hidden' && navigator.sendBeacon) {
+            navigator.sendBeacon(endpoint, JSON.stringify(payload));
+        }
+        else {
+            await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                keepalive: true,
+            });
+        }
+        _log('Events sent', { count: events.length });
+    }
+    catch (err) {
+        console.error('[Kodo] Failed to send events:', err);
+        _eventQueue.unshift(...events);
+    }
+}
+function setupGlobalHandlers() {
+    window.addEventListener('error', (event) => {
+        if (event.error) {
+            captureException(event.error);
+        }
+        else {
+            const err = new Error(event.message);
+            captureException(err, {
+                source: event.filename,
+                lineno: event.lineno,
+                colno: event.colno,
+            });
+        }
+    });
+    window.addEventListener('unhandledrejection', (event) => {
+        const err = event.reason instanceof Error
+            ? event.reason
+            : new Error(String(event.reason));
+        captureException(err, { type: 'unhandled_promise' });
+    });
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+            flush();
+        }
+    });
+    window.addEventListener('beforeunload', () => {
+        flush();
+    });
+}
+function setupBreadcrumbCapture() {
+    // Console capture
+    const originalConsole = {
+        log: console.log,
+        info: console.info,
+        warn: console.warn,
+        error: console.error,
+    };
+    ['log', 'info', 'warn', 'error'].forEach((level) => {
+        console[level] = (...args) => {
+            addBreadcrumb({
+                category: 'console',
+                message: args.map(String).join(' ').substring(0, 500),
+                level: level === 'log' ? 'info' : level === 'warn' ? 'warning' : level,
+            });
+            originalConsole[level](...args);
+        };
+    });
+    // Click capture
+    document.addEventListener('click', (event) => {
+        const target = event.target;
+        const selector = getElementSelector(target);
+        addBreadcrumb({
+            category: 'click',
+            message: `Click on ${selector}`,
+            data: {
+                selector,
+                text: target.textContent?.substring(0, 100),
+            },
+        });
+    }, true);
+    // Navigation capture
+    const originalPushState = history.pushState;
+    history.pushState = function (...args) {
+        addBreadcrumb({
+            category: 'navigation',
+            message: `Navigate to ${args[2]}`,
+            data: { from: window.location.href, to: String(args[2]) },
+        });
+        return originalPushState.apply(this, args);
+    };
+    window.addEventListener('popstate', () => {
+        addBreadcrumb({
+            category: 'navigation',
+            message: `Navigate to ${window.location.href}`,
+        });
+    });
+    // Fetch capture
+    const originalFetch = window.fetch;
+    window.fetch = async function (input, init) {
+        const url = typeof input === 'string' ? input : input instanceof Request ? input.url : String(input);
+        const method = init?.method || 'GET';
+        try {
+            const response = await originalFetch.apply(this, [input, init]);
+            addBreadcrumb({
+                category: 'fetch',
+                message: `${method} ${url}`,
+                level: response.ok ? 'info' : 'error',
+                data: { method, url, status: response.status },
+            });
+            return response;
+        }
+        catch (err) {
+            addBreadcrumb({
+                category: 'fetch',
+                message: `${method} ${url}`,
+                level: 'error',
+                data: { method, url, error: String(err) },
+            });
+            throw err;
+        }
+    };
+    // XHR capture
+    const originalXHROpen = XMLHttpRequest.prototype.open;
+    const originalXHRSend = XMLHttpRequest.prototype.send;
+    XMLHttpRequest.prototype.open = function (method, url, async, username, password) {
+        this._kodo = {
+            method,
+            url: String(url),
+        };
+        return originalXHROpen.call(this, method, url, async ?? true, username, password);
+    };
+    XMLHttpRequest.prototype.send = function (body) {
+        const xhr = this;
+        const kodoData = xhr._kodo;
+        xhr.addEventListener('loadend', () => {
+            if (kodoData) {
+                addBreadcrumb({
+                    category: 'xhr',
+                    message: `${kodoData.method} ${kodoData.url}`,
+                    level: xhr.status >= 400 ? 'error' : 'info',
+                    data: { method: kodoData.method, url: kodoData.url, status: xhr.status },
+                });
+            }
+        });
+        return originalXHRSend.call(this, body);
+    };
+}
+function getElementSelector(element) {
+    if (element.id)
+        return `#${element.id}`;
+    if (element.className && typeof element.className === 'string') {
+        const classes = element.className.split(' ').filter(Boolean).slice(0, 2).join('.');
+        if (classes)
+            return `${element.tagName.toLowerCase()}.${classes}`;
+    }
+    return element.tagName.toLowerCase();
+}
+function getBrowserContext() {
+    const nav = navigator;
+    const perf = performance;
+    const context = {
+        viewport: {
+            width: window.innerWidth,
+            height: window.innerHeight,
+        },
+        devicePixelRatio: window.devicePixelRatio || 1,
+        language: navigator.language,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    };
+    // Network Information API (Chrome/Edge/Opera)
+    if (nav.connection) {
+        context.connection = {
+            effectiveType: nav.connection.effectiveType || 'unknown',
+            downlink: nav.connection.downlink,
+            rtt: nav.connection.rtt,
+        };
+    }
+    // Memory API (Chrome only)
+    if (perf.memory) {
+        context.memory = {
+            jsHeapSizeLimit: perf.memory.jsHeapSizeLimit,
+            totalJSHeapSize: perf.memory.totalJSHeapSize,
+            usedJSHeapSize: perf.memory.usedJSHeapSize,
+        };
+    }
+    return context;
+}
+function captureWebVitals() {
+    if (!('PerformanceObserver' in window))
+        return;
+    // LCP with element metadata
+    try {
+        const lcpObserver = new PerformanceObserver((list) => {
+            const entries = list.getEntries();
+            const lastEntry = entries[entries.length - 1];
+            if (lastEntry) {
+                const metadata = {};
+                // Capture LCP element selector
+                if (lastEntry.element) {
+                    metadata.element = getElementSelector(lastEntry.element);
+                    metadata.elementTag = lastEntry.element.tagName.toLowerCase();
+                }
+                // Capture resource URL (for images/videos)
+                if (lastEntry.url) {
+                    metadata.url = lastEntry.url;
+                }
+                // Capture element size
+                if (lastEntry.size) {
+                    metadata.size = lastEntry.size;
+                }
+                sendVital('LCP', lastEntry.startTime, metadata);
+            }
+        });
+        lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });
+    }
+    catch { /* not supported */ }
+    // FID with event type metadata
+    try {
+        const fidObserver = new PerformanceObserver((list) => {
+            const entries = list.getEntries();
+            const firstEntry = entries[0];
+            if (firstEntry) {
+                const delay = firstEntry.processingStart - firstEntry.startTime;
+                const metadata = {
+                    eventType: firstEntry.name, // 'click', 'keydown', etc.
+                };
+                if (firstEntry.processingEnd) {
+                    metadata.processingTime = firstEntry.processingEnd - firstEntry.processingStart;
+                }
+                sendVital('FID', delay, metadata);
+            }
+        });
+        fidObserver.observe({ type: 'first-input', buffered: true });
+    }
+    catch { /* not supported */ }
+    // CLS with shift source tracking
+    try {
+        let clsValue = 0;
+        let largestShift = 0;
+        let largestShiftSources = [];
+        const clsObserver = new PerformanceObserver((list) => {
+            for (const entry of list.getEntries()) {
+                if (!entry.hadRecentInput) {
+                    clsValue += entry.value;
+                    // Track largest shift for debugging
+                    if (entry.value > largestShift) {
+                        largestShift = entry.value;
+                        largestShiftSources = (entry.sources || [])
+                            .filter(s => s.node)
+                            .slice(0, 3)
+                            .map(s => ({
+                            element: getElementSelector(s.node),
+                            score: entry.value,
+                        }));
+                    }
+                }
+            }
+        });
+        clsObserver.observe({ type: 'layout-shift', buffered: true });
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'hidden' && clsValue > 0) {
+                sendVital('CLS', clsValue, {
+                    largestShift,
+                    sources: largestShiftSources,
+                });
+            }
+        });
+    }
+    catch { /* not supported */ }
+}
+function sendVital(metric, value, metadata) {
+    if (!_config || !_sessionId)
+        return;
+    const rating = getVitalRating(metric, value);
+    const event = {
+        type: 'vital',
+        timestamp: Date.now(),
+        session_id: _sessionId,
+        url: window.location.href,
+        user_agent: navigator.userAgent,
+        service: _config.service || null,
+        release: _config.release || null,
+        environment: _config.environment || detectEnvironment(),
+        data: { metric, value, rating, ...metadata },
+    };
+    queueEvent(event);
+}
+function getVitalRating(metric, value) {
+    switch (metric) {
+        case 'LCP':
+            return value <= 2500 ? 'good' : value <= 4000 ? 'needs_improvement' : 'poor';
+        case 'FID':
+            return value <= 100 ? 'good' : value <= 300 ? 'needs_improvement' : 'poor';
+        case 'CLS':
+            return value <= 0.1 ? 'good' : value <= 0.25 ? 'needs_improvement' : 'poor';
+        default:
+            return 'good';
+    }
+}
+// =============================================================================
+// Export
+// =============================================================================
+const Kodo = {
+    init,
+    setUser,
+    addBreadcrumb,
+    captureException,
+    flush,
+    // Logging
+    log,
+    debug,
+    info,
+    warn,
+    error,
+    fatal,
+    // Tracing
+    startTrace,
+    trace,
+};
+export default Kodo;
+export { init, setUser, addBreadcrumb, captureException, flush, log, debug, info, warn, error, fatal, startTrace, trace };
+//# sourceMappingURL=browser.js.map