@cloff/sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,1194 @@
+import { createClient, SupabaseClient } from '@supabase/supabase-js';
+
+export interface TrackerConfig {
+  supabaseUrl?: string;
+  supabaseAnonKey?: string;
+  debug?: boolean;
+  autoTrackPageViews?: boolean;
+  userId?: string | (() => string | null | undefined);
+  enableErrors?: boolean;
+  enableAPM?: boolean;
+  enableCanisterAPM?: boolean;
+  captureConsole?: boolean;
+}
+
+// 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 {
+  private apiKey: string;
+  private supabase: SupabaseClient;
+  private debug: boolean;
+  private sessionId: string | null = null;
+  private configUserId: string | (() => string | null | undefined) | null = null;
+
+  private enableErrors: boolean;
+  private enableAPM: boolean;
+  private enableCanisterAPM: boolean;
+  private captureConsole: boolean;
+  private breadcrumbs: Array<{ timestamp: string; message: string; category: string; metadata?: any }> = [];
+  private maxBreadcrumbs = 50;
+
+  private vitals = {
+    loadTime: null as number | null,
+    lcp: null as number | null,
+    cls: 0,
+    inp: null as number | null
+  };
+
+  constructor(apiKey: string, config?: TrackerConfig) {
+    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
+   */
+  private getDeviceType(): string {
+    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
+   */
+  private getBrowser(): string {
+    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
+   */
+  private getOS(): string {
+    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
+   */
+  private getLocation(): string {
+    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
+   */
+  private 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
+   */
+  private generateUUID(): string {
+    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
+   */
+  private async getSessionId(userId: string): Promise<string> {
+    if (this.sessionId) {
+      if (typeof window !== 'undefined') {
+        try {
+          sessionStorage.setItem('socio_dau_session_ts', String(Date.now()));
+        } catch (e) { }
+      }
+      return this.sessionId;
+    }
+
+    let sid: string | null = 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;
+  }
+
+  private async registerSession(sid: string, userId: string) {
+    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
+    });
+  }
+
+  private async pingSession(sid: string, userId: string) {
+    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
+   */
+  private setupVitalsObserver() {
+    if (typeof window === 'undefined') return;
+
+    const getLoadTime = () => {
+      try {
+        const perf = window.performance;
+        if (perf) {
+          const nav = perf.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
+          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 as any).hadRecentInput) {
+              this.vitals.cls += (entry as any).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 as any).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
+   */
+  private setupClickObserver() {
+    if (typeof window === 'undefined') return;
+    window.addEventListener('click', (e) => {
+      try {
+        const target = e.target as HTMLElement;
+        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
+   */
+  private setupConsoleObserver() {
+    if (typeof window === 'undefined') return;
+    const self = this;
+    const originalWarn = console.warn;
+    const originalError = console.error;
+
+    console.warn = function (...args: any[]) {
+      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: any[]) {
+      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
+   */
+  private 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
+   */
+  private setupFetchInterception() {
+    if (typeof window === 'undefined' || !window.fetch) return;
+
+    const self = this;
+    const originalFetch = window.fetch;
+
+    window.fetch = async function (input: RequestInfo | URL, init?: RequestInit) {
+      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: any) {
+        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: 'query' | 'update', durationMs: number, requestSize?: number): number {
+    if (callType === 'query') return 0;
+    const BASE_FEE = 5_000_000;
+    const INSTR_PER_MS = 500_000;
+    const BYTE_FEE = 2_000;
+    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
+   */
+  public trackCanisterCall(canisterId: string, method: string, status: 'success' | 'error', durationMs?: number, metadata?: any) {
+    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
+   */
+  public addBreadcrumb(message: string, category = 'manual', metadata?: any) {
+    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: string | number, force = false): Promise<{ success: boolean; error?: string }> {
+    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: string | number,
+    options?: { path?: string; title?: string; referrer?: string }
+  ): Promise<{ success: boolean; error?: string }> {
+    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: any) {
+      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: string | number,
+    eventName: string,
+    properties?: Record<string, any>
+  ): Promise<{ success: boolean; error?: string }> {
+    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: any) {
+      const errMsg = err?.message || String(err);
+      this.logError('Failed during trackEvent:', errMsg);
+      return { success: false, error: errMsg };
+    }
+  }
+
+  /**
+   * Log an exception manually to the database
+   */
+  public async captureException(
+    error: any,
+    extraContext?: any
+  ): Promise<{ success: boolean; error?: string }> {
+    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
+   */
+  public async captureMessage(
+    message: string,
+    severity: 'error' | 'warning' | 'info' = 'error',
+    extraContext?: any
+  ): Promise<{ success: boolean; error?: string }> {
+    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
+   */
+  private async logErrorToDatabase(
+    message: string,
+    stack: string | undefined,
+    severity: 'error' | 'warning' | 'info',
+    handled: boolean,
+    extraContext?: any
+  ): Promise<{ success: boolean; error?: string }> {
+    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: any) {
+      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
+   */
+  public async trackPerformanceSpan(
+    name: string,
+    durationMs: number,
+    entryType = 'custom',
+    metadata?: any
+  ): Promise<{ success: boolean; error?: string }> {
+    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: any) {
+      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
+   */
+  public async trackCanisterSpan(
+    canisterId: string,
+    methodName: string,
+    callType: 'query' | 'update',
+    durationMs: number,
+    status: 'success' | 'reject' | 'error' = 'success',
+    errorMsg?: string,
+    requestSize?: number,
+    responseSize?: number
+  ): Promise<{ success: boolean; error?: string }> {
+    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: any) {
+      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
+   */
+  public wrapHttpAgent<T>(agent: T): T {
+    if (!this.enableCanisterAPM) return agent;
+
+    const self = this;
+    const proto = Object.getPrototypeOf(agent);
+
+    // Only wrap if not already wrapped
+    if ((agent as any).__socioDauWrapped) return agent;
+
+    // Wrap query
+    if (typeof (agent as any).query === 'function') {
+      const originalQuery = proto.query.bind(agent);
+      (agent as any).query = async function (
+        canisterId: any,
+        fields: { methodName: string; arg: any },
+        ...args: any[]
+      ) {
+        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: any) {
+          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 as any).call === 'function') {
+      const originalCall = proto.call.bind(agent);
+      (agent as any).call = async function (
+        canisterId: any,
+        fields: { methodName: string; arg: any },
+        ...args: any[]
+      ) {
+        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: any) {
+          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 as any).__socioDauWrapped = true;
+    return agent;
+  }
+
+  /**
+   * Start a performance span timer
+   */
+  public startSpan(name: string, entryType = 'custom') {
+    const startTime = performance.now();
+    const self = this;
+
+    return {
+      end: async (metadata?: any) => {
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        await self.trackPerformanceSpan(name, duration, entryType, metadata);
+      }
+    };
+  }
+
+  /**
+   * Measure latency of a function and resolve its result
+   */
+  public async measure<T>(
+    name: string,
+    fn: () => Promise<T> | T,
+    entryType = 'custom',
+    metadata?: any
+  ): Promise<T> {
+    const span = this.startSpan(name, entryType);
+    try {
+      const result = await fn();
+      await span.end({ ...metadata, success: true });
+      return result;
+    } catch (error: any) {
+      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: string,
+    steps: string[]
+  ): Promise<{ success: boolean; error?: string }> {
+    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
+    });
+  }
+
+  private resolveUserId(): string | null {
+    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
+   */
+  private setupAutoTracking(userIdParam: string | (() => string | null | undefined)) {
+    if (typeof window === 'undefined') return;
+
+    const getUserId = (): string | null => {
+      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: 'pushState' | 'replaceState') => {
+      const original = window.history[type];
+      return (...args: any[]) => {
+        const result = original.apply(window.history, args as any);
+        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);
+  }
+
+  private 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);
+    }
+  }
+
+  private isOnline(): boolean {
+    if (typeof window === 'undefined') return true;
+    if (typeof navigator === 'undefined') return true;
+    return navigator.onLine;
+  }
+
+  private isNetworkError(error: any): boolean {
+    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")
+    );
+  }
+
+  private getQueueKey(): string {
+    return `socio_telemetry_queue_${this.apiKey}`;
+  }
+
+  private getOfflineQueue(): Array<{ method: string; params: any }> {
+    if (typeof window === 'undefined') return [];
+    try {
+      const val = localStorage.getItem(this.getQueueKey());
+      return val ? JSON.parse(val) : [];
+    } catch (e) {
+      return [];
+    }
+  }
+
+  private saveOfflineQueue(queue: Array<{ method: string; params: any }>) {
+    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);
+    }
+  }
+
+  private enqueueOfflineAction(methodName: string, params: any) {
+    this.logDebug(`Queueing offline event: [${methodName}]`);
+    const queue = this.getOfflineQueue();
+    queue.push({ method: methodName, params });
+    this.saveOfflineQueue(queue);
+  }
+
+  private isFlushing = false;
+
+  private 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;
+    }
+  }
+
+  private async executeRpc(methodName: string, params: any): Promise<{ success: boolean; error?: string }> {
+    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 as any;
+      if (res && res.ok === false) {
+        this.logError(`${methodName} execution failed:`, res.error);
+        return { success: false, error: res.error };
+      }
+
+      return { success: true };
+    } catch (err: any) {
+      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) };
+    }
+  }
+
+  private logDebug(message: string, ...args: any[]) {
+    if (this.debug) {
+      console.log(`[SocioDAU Debug] ${message}`, ...args);
+    }
+  }
+
+  private logError(message: string, ...args: any[]) {
+    console.error(`[Clof Error] ${message}`, ...args);
+  }
+}
+
+export { Clof as SocioDauTracker, Clof as ClofTracker };