@cloff/sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,1049 @@
+import { createClient } from '@supabase/supabase-js';
+// Default central database credentials (this points to our host project)
+const DEFAULT_SUPABASE_URL = 'https://edhkrzyiiznotsmblbrt.supabase.co';
+const DEFAULT_SUPABASE_ANON_KEY = 'sb_publishable_EzjTe8cJu-8gZmdccQr4aA_iZY8WIxL';
+export class Clof {
+    constructor(apiKey, config) {
+        this.sessionId = null;
+        this.configUserId = null;
+        this.breadcrumbs = [];
+        this.maxBreadcrumbs = 50;
+        this.vitals = {
+            loadTime: null,
+            lcp: null,
+            cls: 0,
+            inp: null
+        };
+        this.isFlushing = false;
+        if (!apiKey) {
+            throw new Error('Clof: API Key is required.');
+        }
+        this.apiKey = apiKey;
+        this.debug = config?.debug ?? false;
+        this.configUserId = config?.userId ?? null;
+        this.enableErrors = config?.enableErrors ?? true;
+        this.enableAPM = config?.enableAPM ?? true;
+        this.enableCanisterAPM = config?.enableCanisterAPM ?? true;
+        this.captureConsole = config?.captureConsole ?? false;
+        const url = config?.supabaseUrl ?? DEFAULT_SUPABASE_URL;
+        const anonKey = config?.supabaseAnonKey ?? DEFAULT_SUPABASE_ANON_KEY;
+        this.supabase = createClient(url, anonKey);
+        this.setupVitalsObserver();
+        if (this.enableErrors) {
+            this.setupErrorObservers();
+            this.setupClickObserver();
+            if (this.captureConsole) {
+                this.setupConsoleObserver();
+            }
+        }
+        if (this.enableErrors || this.enableAPM) {
+            this.setupFetchInterception();
+        }
+        if (config?.autoTrackPageViews && config.userId) {
+            this.setupAutoTracking(config.userId);
+        }
+        this.setupOnlineListener();
+    }
+    /**
+     * Helper to identify device form-factor from Navigator UA string
+     */
+    getDeviceType() {
+        if (typeof window === 'undefined' || !navigator.userAgent)
+            return 'Desktop';
+        const ua = navigator.userAgent;
+        if (/(tablet|ipad|playbook|silk)|(android(?!.*mobi))/i.test(ua))
+            return 'Tablet';
+        if (/Mobile|iP(hone|od)|Android|BlackBerry|IEMobile|Kindle|Silk-Accelerated|(hpw|web)OS|Opera M(obi|ini)/i.test(ua)) {
+            return 'Mobile';
+        }
+        return 'Desktop';
+    }
+    /**
+     * Helper to extract browser name from UA string
+     */
+    getBrowser() {
+        if (typeof window === 'undefined' || !navigator.userAgent)
+            return 'unknown';
+        const ua = navigator.userAgent;
+        if (/opr\/|opera/i.test(ua))
+            return 'Opera';
+        if (/edg/i.test(ua))
+            return 'Edge';
+        if (/chrome|crios/i.test(ua))
+            return 'Chrome';
+        if (/firefox|fxios/i.test(ua))
+            return 'Firefox';
+        if (/safari/i.test(ua))
+            return 'Safari';
+        return 'unknown';
+    }
+    /**
+     * Helper to extract OS name from UA string
+     */
+    getOS() {
+        if (typeof window === 'undefined' || !navigator.userAgent)
+            return 'unknown';
+        const ua = navigator.userAgent;
+        if (/iphone|ipad|ipod/i.test(ua))
+            return 'iOS';
+        if (/android/i.test(ua))
+            return 'Android';
+        if (/mac/i.test(ua))
+            return 'macOS';
+        if (/win/i.test(ua))
+            return 'Windows';
+        if (/linux/i.test(ua))
+            return 'Linux';
+        return 'unknown';
+    }
+    /**
+     * Helper to retrieve timezone identifier as location
+     */
+    getLocation() {
+        try {
+            if (typeof Intl !== 'undefined' && Intl.DateTimeFormat) {
+                return Intl.DateTimeFormat().resolvedOptions().timeZone || 'unknown';
+            }
+        }
+        catch (e) {
+            // Fallback
+        }
+        return 'unknown';
+    }
+    /**
+     * Helper to parse UTM parameters from search URL
+     */
+    getUTMParams() {
+        if (typeof window === 'undefined')
+            return { utm_source: null, utm_medium: null, utm_campaign: null };
+        try {
+            const params = new URLSearchParams(window.location.search);
+            return {
+                utm_source: params.get('utm_source'),
+                utm_medium: params.get('utm_medium'),
+                utm_campaign: params.get('utm_campaign')
+            };
+        }
+        catch (e) {
+            return { utm_source: null, utm_medium: null, utm_campaign: null };
+        }
+    }
+    /**
+     * Generate UUID v4
+     */
+    generateUUID() {
+        if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        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);
+        });
+    }
+    /**
+     * Resolve and ping the current user session
+     */
+    async getSessionId(userId) {
+        if (this.sessionId) {
+            if (typeof window !== 'undefined') {
+                try {
+                    sessionStorage.setItem('socio_dau_session_ts', String(Date.now()));
+                }
+                catch (e) { }
+            }
+            return this.sessionId;
+        }
+        let sid = null;
+        let isNew = false;
+        const now = Date.now();
+        const expiry = 30 * 60 * 1000; // 30 minutes
+        if (typeof window !== 'undefined') {
+            try {
+                const cachedId = sessionStorage.getItem('socio_dau_session_id');
+                const cachedTs = sessionStorage.getItem('socio_dau_session_ts');
+                if (cachedId && cachedTs && now - Number(cachedTs) < expiry) {
+                    sid = cachedId;
+                    sessionStorage.setItem('socio_dau_session_ts', String(now));
+                }
+                else {
+                    sid = this.generateUUID();
+                    sessionStorage.setItem('socio_dau_session_id', sid);
+                    sessionStorage.setItem('socio_dau_session_ts', String(now));
+                    isNew = true;
+                }
+            }
+            catch (e) {
+                sid = this.generateUUID();
+                isNew = true;
+            }
+        }
+        else {
+            sid = this.generateUUID();
+            isNew = true;
+        }
+        this.sessionId = sid;
+        if (isNew) {
+            await this.registerSession(sid, userId);
+        }
+        else {
+            this.pingSession(sid, userId);
+        }
+        return sid;
+    }
+    async registerSession(sid, userId) {
+        const utm = this.getUTMParams();
+        const deviceType = this.getDeviceType();
+        const browser = this.getBrowser();
+        const os = this.getOS();
+        const location = this.getLocation();
+        await this.executeRpc('start_or_ping_session', {
+            p_session_id: sid,
+            p_api_key: this.apiKey,
+            p_user_id: userId,
+            p_device_type: deviceType,
+            p_browser: browser,
+            p_os: os,
+            p_location: location,
+            p_utm_source: utm.utm_source,
+            p_utm_medium: utm.utm_medium,
+            p_utm_campaign: utm.utm_campaign
+        });
+    }
+    async pingSession(sid, userId) {
+        await this.executeRpc('start_or_ping_session', {
+            p_session_id: sid,
+            p_api_key: this.apiKey,
+            p_user_id: userId,
+            p_device_type: this.getDeviceType(),
+            p_browser: this.getBrowser(),
+            p_os: this.getOS(),
+            p_location: this.getLocation()
+        });
+    }
+    /**
+     * Observes page loading performance and layout stability
+     */
+    setupVitalsObserver() {
+        if (typeof window === 'undefined')
+            return;
+        const getLoadTime = () => {
+            try {
+                const perf = window.performance;
+                if (perf) {
+                    const nav = perf.getEntriesByType('navigation')[0];
+                    if (nav) {
+                        this.vitals.loadTime = Math.round(nav.duration || nav.loadEventEnd - nav.startTime);
+                    }
+                    else {
+                        const timing = perf.timing;
+                        if (timing) {
+                            this.vitals.loadTime = timing.loadEventEnd - timing.navigationStart;
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                // Fallback
+            }
+        };
+        if (document.readyState === 'complete') {
+            getLoadTime();
+        }
+        else {
+            window.addEventListener('load', () => setTimeout(getLoadTime, 0));
+        }
+        if (typeof PerformanceObserver !== 'undefined') {
+            try {
+                const lcpObserver = new PerformanceObserver((entryList) => {
+                    const entries = entryList.getEntries();
+                    const lastEntry = entries[entries.length - 1];
+                    this.vitals.lcp = Math.round(lastEntry.startTime);
+                });
+                lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });
+                const clsObserver = new PerformanceObserver((entryList) => {
+                    for (const entry of entryList.getEntries()) {
+                        if (!entry.hadRecentInput) {
+                            this.vitals.cls += entry.value;
+                        }
+                    }
+                });
+                clsObserver.observe({ type: 'layout-shift', buffered: true });
+                const inpObserver = new PerformanceObserver((entryList) => {
+                    const entries = entryList.getEntries();
+                    const lastEntry = entries[entries.length - 1];
+                    this.vitals.inp = Math.round(lastEntry.duration || lastEntry.processingStart - lastEntry.startTime);
+                });
+                inpObserver.observe({ type: 'first-input', buffered: true });
+            }
+            catch (e) {
+                this.logDebug('PerformanceObserver setup error:', e);
+            }
+        }
+    }
+    /**
+     * Setup a click listener to log interaction breadcrumbs
+     */
+    setupClickObserver() {
+        if (typeof window === 'undefined')
+            return;
+        window.addEventListener('click', (e) => {
+            try {
+                const target = e.target;
+                if (!target)
+                    return;
+                let desc = target.tagName.toLowerCase();
+                if (target.id)
+                    desc += `#${target.id}`;
+                if (target.className && typeof target.className === 'string') {
+                    desc += `.${target.className.trim().split(/\s+/).join('.')}`;
+                }
+                const testId = target.getAttribute('data-testid');
+                const text = target.innerText?.slice(0, 30).trim();
+                this.addBreadcrumb(`Click on ${desc}`, 'click', {
+                    testId,
+                    text,
+                    tagName: target.tagName
+                });
+            }
+            catch (err) {
+                // Safe catch
+            }
+        }, { passive: true });
+    }
+    /**
+     * Intercept console warnings & errors to record breadcrumbs
+     */
+    setupConsoleObserver() {
+        if (typeof window === 'undefined')
+            return;
+        const self = this;
+        const originalWarn = console.warn;
+        const originalError = console.error;
+        console.warn = function (...args) {
+            try {
+                const msg = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+                self.addBreadcrumb(msg, 'console', { level: 'warning' });
+            }
+            catch (e) { }
+            originalWarn.apply(console, args);
+        };
+        console.error = function (...args) {
+            try {
+                const msg = args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ');
+                self.addBreadcrumb(msg, 'console', { level: 'error' });
+            }
+            catch (e) { }
+            originalError.apply(console, args);
+        };
+    }
+    /**
+     * Listen to global unhandled exceptions and promise rejections
+     */
+    setupErrorObservers() {
+        if (typeof window === 'undefined')
+            return;
+        window.addEventListener('error', (event) => {
+            try {
+                this.captureException(event.error || event.message, {
+                    filename: event.filename,
+                    lineno: event.lineno,
+                    colno: event.colno,
+                    unhandled: true
+                });
+            }
+            catch (e) {
+                this.logError('Error observer failed:', e);
+            }
+        });
+        window.addEventListener('unhandledrejection', (event) => {
+            try {
+                const reason = event.reason;
+                const msg = reason instanceof Error ? reason.message : String(reason);
+                this.captureException(reason || msg, {
+                    unhandled: true,
+                    rejection: true
+                });
+            }
+            catch (e) {
+                this.logError('Unhandledrejection observer failed:', e);
+            }
+        });
+    }
+    /**
+     * Hook global fetch to auto-trace API durations and catch status >= 400 silent errors
+     */
+    setupFetchInterception() {
+        if (typeof window === 'undefined' || !window.fetch)
+            return;
+        const self = this;
+        const originalFetch = window.fetch;
+        window.fetch = async function (input, init) {
+            const url = typeof input === 'string' ? input : (input instanceof URL ? input.href : input.url);
+            const method = init?.method || 'GET';
+            // Prevent recursive requests if they hit our Supabase DB
+            if (url.includes('supabase.co') || url.includes('supabaseUrl')) {
+                return originalFetch.apply(this, [input, init]);
+            }
+            const startTime = performance.now();
+            try {
+                const response = await originalFetch.apply(this, [input, init]);
+                const duration = performance.now() - startTime;
+                const canisterMatch = url.match(/\/api\/v2\/canister\/([a-z0-9-]{5,})\/(query|call|read_state)/);
+                if (canisterMatch) {
+                    const canisterId = canisterMatch[1];
+                    const action = canisterMatch[2];
+                    self.addBreadcrumb(`Canister Call: ${action} on ${canisterId} (${response.status})`, 'contract', {
+                        canisterId,
+                        method: action,
+                        status: response.status >= 400 ? 'error' : 'success',
+                        durationMs: Math.round(duration),
+                        url
+                    });
+                }
+                else {
+                    self.addBreadcrumb(`Fetch resolve: ${method} ${url} (${response.status})`, 'fetch', {
+                        status: response.status,
+                        durationMs: Math.round(duration)
+                    });
+                }
+                if (self.enableAPM) {
+                    self.trackPerformanceSpan(url, duration, 'api_call', {
+                        method,
+                        status: response.status
+                    }).catch(() => { });
+                }
+                if (response.status >= 400 && self.enableErrors) {
+                    self.logErrorToDatabase(`HTTP ${response.status}: Fetch failed on ${method} ${url}`, new Error(`Fetch failed: ${response.status}`).stack, 'warning', true, {
+                        url,
+                        method,
+                        status: response.status,
+                        statusText: response.statusText
+                    }).catch(() => { });
+                }
+                return response;
+            }
+            catch (err) {
+                const duration = performance.now() - startTime;
+                const errMsg = err?.message || String(err);
+                const canisterMatch = url.match(/\/api\/v2\/canister\/([a-z0-9-]{5,})\/(query|call|read_state)/);
+                if (canisterMatch) {
+                    const canisterId = canisterMatch[1];
+                    const action = canisterMatch[2];
+                    self.addBreadcrumb(`Canister Call network error: ${action} on ${canisterId} (${errMsg})`, 'contract', {
+                        canisterId,
+                        method: action,
+                        status: 'error',
+                        durationMs: Math.round(duration),
+                        error: errMsg,
+                        url
+                    });
+                }
+                else {
+                    self.addBreadcrumb(`Fetch network error: ${method} ${url} (${errMsg})`, 'fetch', {
+                        error: errMsg,
+                        durationMs: Math.round(duration)
+                    });
+                }
+                if (self.enableAPM) {
+                    self.trackPerformanceSpan(url, duration, 'api_call', {
+                        method,
+                        error: errMsg
+                    }).catch(() => { });
+                }
+                if (self.enableErrors) {
+                    self.logErrorToDatabase(`Network Error: Fetch failed on ${method} ${url} - ${errMsg}`, err instanceof Error ? err.stack : new Error(`Network failure`).stack, 'error', true, {
+                        url,
+                        method,
+                        error: errMsg
+                    }).catch(() => { });
+                }
+                throw err;
+            }
+        };
+    }
+    /**
+     * Estimate cycles consumed by a canister call using client-side heuristics.
+     * Query calls are free on ICP. Update calls incur:
+     *   base_fee (5M) + est_instructions × 1 cycle/instruction + ingress_bytes × 2000 cycles/byte
+     */
+    static estimateCanisterCycles(callType, durationMs, requestSize) {
+        if (callType === 'query')
+            return 0;
+        const BASE_FEE = 5000000;
+        const INSTR_PER_MS = 500000;
+        const BYTE_FEE = 2000;
+        const estInstructions = Math.round(durationMs * INSTR_PER_MS);
+        const estBytes = (requestSize || 0) * BYTE_FEE;
+        return BASE_FEE + (estInstructions * 1) + estBytes;
+    }
+    /**
+     * Log a canister call action manually
+     */
+    trackCanisterCall(canisterId, method, status, durationMs, metadata) {
+        const estimatedCycles = durationMs ? Clof.estimateCanisterCycles('update', durationMs) : undefined;
+        this.addBreadcrumb(`Canister Call: ${method} on ${canisterId} (${status})`, 'contract', {
+            canisterId,
+            method,
+            status,
+            durationMs,
+            estimatedCycles,
+            ...metadata
+        });
+    }
+    /**
+     * Add manual trace breadcrumbs
+     */
+    addBreadcrumb(message, category = 'manual', metadata) {
+        if (!this.enableErrors)
+            return;
+        this.breadcrumbs.push({
+            timestamp: new Date().toISOString(),
+            message,
+            category,
+            metadata
+        });
+        if (this.breadcrumbs.length > this.maxBreadcrumbs) {
+            this.breadcrumbs.shift();
+        }
+        this.logDebug(`Breadcrumb added: [${category}] ${message}`);
+    }
+    /**
+     * Track user activity (Legacy DAU Ping).
+     * Uses localStorage to deduplicate pings on the same day for a given user.
+     */
+    async track(userId, force = false) {
+        const cleanUserId = String(userId).trim();
+        if (!cleanUserId) {
+            this.logError('track() called with empty user ID');
+            return { success: false, error: 'User ID cannot be empty' };
+        }
+        const todayStr = new Date().toISOString().split('T')[0];
+        const cacheKey = `socio_dau_tracked_${this.apiKey}_${cleanUserId}`;
+        if (!force) {
+            try {
+                const lastTrackedDate = localStorage.getItem(cacheKey);
+                if (lastTrackedDate === todayStr) {
+                    this.logDebug(`User ${cleanUserId} already tracked today. Skipping ping.`);
+                    return { success: true };
+                }
+            }
+            catch (err) {
+                this.logError('localStorage error:', err);
+            }
+        }
+        const deviceType = this.getDeviceType();
+        const location = this.getLocation();
+        this.logDebug(`Pinging activity for user ${cleanUserId} (${deviceType}, ${location})...`);
+        const res = await this.executeRpc('track_dau', {
+            p_api_key: this.apiKey,
+            p_user_id: cleanUserId,
+            p_device_type: deviceType,
+            p_location: location
+        });
+        if (res.success) {
+            try {
+                localStorage.setItem(cacheKey, todayStr);
+            }
+            catch (e) { }
+            return { success: true };
+        }
+        return { success: false, error: res.error };
+    }
+    /**
+     * Track specific Page Views.
+     * Logs page navigation events, referrer, and captures performance Web Vitals.
+     */
+    async trackPageView(userId, options) {
+        const cleanUserId = String(userId).trim();
+        if (!cleanUserId) {
+            this.logError('trackPageView() called with empty user ID');
+            return { success: false, error: 'User ID cannot be empty' };
+        }
+        const path = options?.path ?? (typeof window !== 'undefined' ? window.location.pathname : '/');
+        const title = options?.title ?? (typeof document !== 'undefined' ? document.title : undefined);
+        const referrer = options?.referrer ?? (typeof document !== 'undefined' ? document.referrer : undefined);
+        this.addBreadcrumb(`Navigate to ${path}`, 'navigation', { title, referrer });
+        try {
+            const sid = await this.getSessionId(cleanUserId);
+            this.logDebug(`Logging page view: Session: ${sid}, Path: ${path}, Title: ${title}`);
+            const loadTime = this.vitals.loadTime;
+            const lcp = this.vitals.lcp;
+            const cls = this.vitals.cls;
+            const inp = this.vitals.inp;
+            return this.executeRpc('track_page_view_v2', {
+                p_session_id: sid,
+                p_path: path,
+                p_title: title,
+                p_referrer: referrer,
+                p_load_time_ms: loadTime ? Math.round(loadTime) : null,
+                p_lcp_ms: lcp ? Math.round(lcp) : null,
+                p_cls: cls ? Number(cls.toFixed(4)) : null,
+                p_inp_ms: inp ? Math.round(inp) : null
+            });
+        }
+        catch (err) {
+            const errMsg = err?.message || String(err);
+            this.logError('Failed during trackPageView:', errMsg);
+            return { success: false, error: errMsg };
+        }
+    }
+    /**
+     * Track Custom Events (actions, goals, conversions)
+     */
+    async trackEvent(userId, eventName, properties) {
+        const cleanUserId = String(userId).trim();
+        const cleanEventName = String(eventName).trim();
+        if (!cleanUserId) {
+            this.logError('trackEvent() called with empty user ID');
+            return { success: false, error: 'User ID cannot be empty' };
+        }
+        if (!cleanEventName) {
+            this.logError('trackEvent() called with empty event name');
+            return { success: false, error: 'Event name cannot be empty' };
+        }
+        this.addBreadcrumb(`Event triggered: ${cleanEventName}`, 'event', properties);
+        try {
+            const sid = await this.getSessionId(cleanUserId);
+            this.logDebug(`Logging custom event: Session: ${sid}, Event: ${cleanEventName}`);
+            return this.executeRpc('track_custom_event', {
+                p_session_id: sid,
+                p_event_name: cleanEventName,
+                p_properties: properties || null
+            });
+        }
+        catch (err) {
+            const errMsg = err?.message || String(err);
+            this.logError('Failed during trackEvent:', errMsg);
+            return { success: false, error: errMsg };
+        }
+    }
+    /**
+     * Log an exception manually to the database
+     */
+    async captureException(error, extraContext) {
+        if (!this.enableErrors)
+            return { success: false, error: 'Error tracking disabled' };
+        const message = error instanceof Error ? error.message : String(error);
+        const stack = error instanceof Error ? error.stack : new Error().stack;
+        return this.logErrorToDatabase(message, stack, 'error', false, extraContext);
+    }
+    /**
+     * Log a custom severity warning or info message to the database
+     */
+    async captureMessage(message, severity = 'error', extraContext) {
+        if (!this.enableErrors)
+            return { success: false, error: 'Error tracking disabled' };
+        const stack = new Error().stack;
+        return this.logErrorToDatabase(message, stack, severity, true, extraContext);
+    }
+    /**
+     * Helper function to execute error logging RPC
+     */
+    async logErrorToDatabase(message, stack, severity, handled, extraContext) {
+        try {
+            const activeUserId = this.configUserId ? this.resolveUserId() : 'anonymous';
+            const sid = await this.getSessionId(activeUserId || 'anonymous');
+            const context = {
+                browser: this.getBrowser(),
+                os: this.getOS(),
+                device: this.getDeviceType(),
+                location: this.getLocation(),
+                url: typeof window !== 'undefined' ? window.location.href : 'unknown',
+                sdkVersion: '1.0.2',
+                extra: extraContext
+            };
+            return this.executeRpc('track_error', {
+                p_session_id: sid,
+                p_message: message,
+                p_stack: stack || null,
+                p_breadcrumbs: this.breadcrumbs,
+                p_context: context,
+                p_severity: severity,
+                p_handled: handled
+            });
+        }
+        catch (err) {
+            const errMsg = err?.message || String(err);
+            this.logError('Failed to log error to database:', errMsg);
+            return { success: false, error: errMsg };
+        }
+    }
+    /**
+     * Log latency of a duration in milliseconds manually
+     */
+    async trackPerformanceSpan(name, durationMs, entryType = 'custom', metadata) {
+        if (!this.enableAPM)
+            return { success: false, error: 'APM disabled' };
+        try {
+            const activeUserId = this.configUserId ? this.resolveUserId() : 'anonymous';
+            const sid = await this.getSessionId(activeUserId || 'anonymous');
+            return this.executeRpc('track_performance_span', {
+                p_session_id: sid,
+                p_name: name,
+                p_duration_ms: durationMs,
+                p_entry_type: entryType,
+                p_metadata: metadata || null
+            });
+        }
+        catch (err) {
+            const errMsg = err?.message || String(err);
+            this.logError('Failed to track performance span:', errMsg);
+            return { success: false, error: errMsg };
+        }
+    }
+    /**
+     * Log latency of an ICP canister call with method-level granularity
+     */
+    async trackCanisterSpan(canisterId, methodName, callType, durationMs, status = 'success', errorMsg, requestSize, responseSize) {
+        if (!this.enableCanisterAPM)
+            return { success: false, error: 'Canister APM disabled' };
+        try {
+            const activeUserId = this.configUserId ? this.resolveUserId() : 'anonymous';
+            const sid = await this.getSessionId(activeUserId || 'anonymous');
+            const estimatedCycles = Clof.estimateCanisterCycles(callType, durationMs, requestSize);
+            return this.executeRpc('track_canister_call', {
+                p_session_id: sid,
+                p_canister_id: canisterId,
+                p_method_name: methodName,
+                p_call_type: callType,
+                p_duration_ms: durationMs,
+                p_status: status,
+                p_error_msg: errorMsg || null,
+                p_request_size: requestSize || null,
+                p_response_size: responseSize || null,
+                p_estimated_cycles: estimatedCycles
+            });
+        }
+        catch (err) {
+            const errMsg = err?.message || String(err);
+            this.logError('Failed to track canister span:', errMsg);
+            return { success: false, error: errMsg };
+        }
+    }
+    /**
+     * Wrap an @dfinity/agent HttpAgent to intercept canister calls for APM.
+     * Returns the same agent proxied — no @dfinity/agent dependency needed.
+     *
+     * Usage:
+     *   import { HttpAgent } from '@dfinity/agent';
+     *   const agent = new HttpAgent();
+     *   const wrapped = tracker.wrapHttpAgent(agent);
+     *   // use wrapped everywhere instead of agent
+     */
+    wrapHttpAgent(agent) {
+        if (!this.enableCanisterAPM)
+            return agent;
+        const self = this;
+        const proto = Object.getPrototypeOf(agent);
+        // Only wrap if not already wrapped
+        if (agent.__socioDauWrapped)
+            return agent;
+        // Wrap query
+        if (typeof agent.query === 'function') {
+            const originalQuery = proto.query.bind(agent);
+            agent.query = async function (canisterId, fields, ...args) {
+                const startTime = performance.now();
+                const reqSize = fields.arg?.byteLength || 0;
+                try {
+                    const result = await originalQuery(canisterId, fields, ...args);
+                    const duration = performance.now() - startTime;
+                    const cid = typeof canisterId === 'object' && canisterId.toText ? canisterId.toText() : String(canisterId);
+                    self.trackCanisterSpan(cid, fields.methodName, 'query', duration, 'success', undefined, reqSize).catch(() => { });
+                    return result;
+                }
+                catch (err) {
+                    const duration = performance.now() - startTime;
+                    const cid = typeof canisterId === 'object' && canisterId.toText ? canisterId.toText() : String(canisterId);
+                    self.trackCanisterSpan(cid, fields.methodName, 'query', duration, 'error', err?.message || String(err), reqSize).catch(() => { });
+                    throw err;
+                }
+            };
+        }
+        // Wrap update call
+        if (typeof agent.call === 'function') {
+            const originalCall = proto.call.bind(agent);
+            agent.call = async function (canisterId, fields, ...args) {
+                const startTime = performance.now();
+                const reqSize = fields.arg?.byteLength || 0;
+                try {
+                    const result = await originalCall(canisterId, fields, ...args);
+                    const duration = performance.now() - startTime;
+                    const cid = typeof canisterId === 'object' && canisterId.toText ? canisterId.toText() : String(canisterId);
+                    self.addBreadcrumb(`Canister update: ${fields.methodName} on ${cid} (${Math.round(duration)}ms)`, 'contract', {
+                        canisterId: cid,
+                        methodName: fields.methodName,
+                        callType: 'update',
+                        durationMs: Math.round(duration),
+                        status: 'success',
+                        requestSize: reqSize
+                    });
+                    self.trackCanisterSpan(cid, fields.methodName, 'update', duration, 'success', undefined, reqSize).catch(() => { });
+                    return result;
+                }
+                catch (err) {
+                    const duration = performance.now() - startTime;
+                    const cid = typeof canisterId === 'object' && canisterId.toText ? canisterId.toText() : String(canisterId);
+                    const errMsg = err?.message || String(err);
+                    self.addBreadcrumb(`Canister update error: ${fields.methodName} on ${cid} (${errMsg})`, 'contract', {
+                        canisterId: cid,
+                        methodName: fields.methodName,
+                        callType: 'update',
+                        durationMs: Math.round(duration),
+                        status: 'error'
+                    });
+                    self.trackCanisterSpan(cid, fields.methodName, 'update', duration, 'error', errMsg, reqSize).catch(() => { });
+                    throw err;
+                }
+            };
+        }
+        agent.__socioDauWrapped = true;
+        return agent;
+    }
+    /**
+     * Start a performance span timer
+     */
+    startSpan(name, entryType = 'custom') {
+        const startTime = performance.now();
+        const self = this;
+        return {
+            end: async (metadata) => {
+                const endTime = performance.now();
+                const duration = endTime - startTime;
+                await self.trackPerformanceSpan(name, duration, entryType, metadata);
+            }
+        };
+    }
+    /**
+     * Measure latency of a function and resolve its result
+     */
+    async measure(name, fn, entryType = 'custom', metadata) {
+        const span = this.startSpan(name, entryType);
+        try {
+            const result = await fn();
+            await span.end({ ...metadata, success: true });
+            return result;
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            await span.end({ ...metadata, success: false, error: errMsg });
+            throw error;
+        }
+    }
+    /**
+     * Define a user funnel for conversion analysis.
+     * Stores the ordered event sequence to the database so the
+     * dashboard can visualize drop-off at each step.
+     *
+     * Example:
+     *   tracker.defineFunnel('Swap Flow', [
+     *     'connect_wallet',
+     *     'click_swap_token',
+     *     'sign_transaction',
+     *     'swap_success'
+     *   ])
+     */
+    async defineFunnel(name, steps) {
+        const cleanName = String(name).trim();
+        if (!cleanName) {
+            this.logError('defineFunnel() called with empty name');
+            return { success: false, error: 'Funnel name cannot be empty' };
+        }
+        if (!steps || steps.length < 2) {
+            this.logError('defineFunnel() called with fewer than 2 steps');
+            return { success: false, error: 'Funnel must have at least 2 steps' };
+        }
+        this.logDebug(`Defining funnel: ${cleanName} [${steps.join(' → ')}]`);
+        return this.executeRpc('upsert_funnel', {
+            p_api_key: this.apiKey,
+            p_owner_did: this.configUserId ? this.resolveUserId() : null,
+            p_name: cleanName,
+            p_steps: steps
+        });
+    }
+    resolveUserId() {
+        if (typeof this.configUserId === 'function') {
+            const id = this.configUserId();
+            return id ? String(id) : null;
+        }
+        return this.configUserId ? String(this.configUserId) : null;
+    }
+    /**
+     * Listen to Single-Page App (SPA) route changes and track page views automatically
+     */
+    setupAutoTracking(userIdParam) {
+        if (typeof window === 'undefined')
+            return;
+        const getUserId = () => {
+            if (typeof userIdParam === 'function') {
+                const id = userIdParam();
+                return id ? String(id) : null;
+            }
+            return userIdParam ? String(userIdParam) : null;
+        };
+        const trackCurrent = () => {
+            const uid = getUserId();
+            if (uid) {
+                this.trackPageView(uid).catch(err => {
+                    this.logError('Auto-track page view failed:', err);
+                });
+            }
+        };
+        if (document.readyState === 'complete') {
+            trackCurrent();
+        }
+        else {
+            window.addEventListener('load', trackCurrent);
+        }
+        const wrapHistory = (type) => {
+            const original = window.history[type];
+            return (...args) => {
+                const result = original.apply(window.history, args);
+                trackCurrent();
+                return result;
+            };
+        };
+        try {
+            window.history.pushState = wrapHistory('pushState');
+            window.history.replaceState = wrapHistory('replaceState');
+        }
+        catch (e) {
+            this.logError('Failed to monkeypatch history API:', e);
+        }
+        window.addEventListener('popstate', trackCurrent);
+    }
+    setupOnlineListener() {
+        if (typeof window !== 'undefined' && window.addEventListener) {
+            window.addEventListener('online', () => {
+                this.logDebug('Device came back online. Flushing queued telemetry events...');
+                this.flushOfflineQueue();
+            });
+            setTimeout(() => {
+                if (this.isOnline()) {
+                    this.flushOfflineQueue();
+                }
+            }, 1000);
+        }
+    }
+    isOnline() {
+        if (typeof window === 'undefined')
+            return true;
+        if (typeof navigator === 'undefined')
+            return true;
+        return navigator.onLine;
+    }
+    isNetworkError(error) {
+        const msg = String(error?.message || error || "").toLowerCase();
+        return (msg.includes("failed to fetch") ||
+            msg.includes("network error") ||
+            msg.includes("load failed") ||
+            msg.includes("networkerror") ||
+            msg.includes("typeerror: fetch failed"));
+    }
+    getQueueKey() {
+        return `socio_telemetry_queue_${this.apiKey}`;
+    }
+    getOfflineQueue() {
+        if (typeof window === 'undefined')
+            return [];
+        try {
+            const val = localStorage.getItem(this.getQueueKey());
+            return val ? JSON.parse(val) : [];
+        }
+        catch (e) {
+            return [];
+        }
+    }
+    saveOfflineQueue(queue) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            if (queue.length > 500) {
+                queue = queue.slice(-500);
+            }
+            localStorage.setItem(this.getQueueKey(), JSON.stringify(queue));
+        }
+        catch (e) {
+            this.logError('Failed to save offline queue to localStorage', e);
+        }
+    }
+    enqueueOfflineAction(methodName, params) {
+        this.logDebug(`Queueing offline event: [${methodName}]`);
+        const queue = this.getOfflineQueue();
+        queue.push({ method: methodName, params });
+        this.saveOfflineQueue(queue);
+    }
+    async flushOfflineQueue() {
+        if (this.isFlushing || typeof window === 'undefined' || !this.isOnline())
+            return;
+        const queue = this.getOfflineQueue();
+        if (queue.length === 0)
+            return;
+        this.isFlushing = true;
+        this.logDebug(`Flushing offline telemetry queue (${queue.length} events)...`);
+        let remainingQueue = [...queue];
+        try {
+            while (remainingQueue.length > 0) {
+                const item = remainingQueue[0];
+                const { data, error } = await this.supabase.rpc(item.method, item.params);
+                if (error) {
+                    if (this.isNetworkError(error)) {
+                        this.logDebug(`Network still down while flushing item: ${error.message}. Aborting flush.`);
+                        break;
+                    }
+                    else {
+                        this.logError(`Dropped failed telemetry item due to non-network error: ${error.message}`);
+                    }
+                }
+                remainingQueue.shift();
+                this.saveOfflineQueue(remainingQueue);
+            }
+        }
+        catch (e) {
+            this.logError('Error during offline queue flush:', e);
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    async executeRpc(methodName, params) {
+        if (typeof window !== 'undefined' && !this.isOnline()) {
+            this.enqueueOfflineAction(methodName, params);
+            return { success: true };
+        }
+        try {
+            const { data, error } = await this.supabase.rpc(methodName, params);
+            if (error) {
+                if (this.isNetworkError(error)) {
+                    this.enqueueOfflineAction(methodName, params);
+                    return { success: true };
+                }
+                this.logError(`${methodName} RPC error:`, error.message);
+                return { success: false, error: error.message };
+            }
+            const res = data;
+            if (res && res.ok === false) {
+                this.logError(`${methodName} execution failed:`, res.error);
+                return { success: false, error: res.error };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            if (this.isNetworkError(err)) {
+                this.enqueueOfflineAction(methodName, params);
+                return { success: true };
+            }
+            this.logError(`${methodName} catch error:`, err);
+            return { success: false, error: err?.message || String(err) };
+        }
+    }
+    logDebug(message, ...args) {
+        if (this.debug) {
+            console.log(`[SocioDAU Debug] ${message}`, ...args);
+        }
+    }
+    logError(message, ...args) {
+        console.error(`[Clof Error] ${message}`, ...args);
+    }
+}
+export { Clof as SocioDauTracker, Clof as ClofTracker };