flowgrid-sdk 1.2.0 → 1.3.0

package/dist/lib/features/analytics/page-views.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Product Analytics - Page View Tracking
+ * @module features/analytics/page-views
+ *
+ * @description
+ * Track page views with rich context including scroll depth, time on page,
+ * referrer information, and user engagement signals.
+ *
+ * @useCases
+ * - Track which pages users visit most frequently
+ * - Measure time spent on content pages
+ * - Identify high bounce rate pages
+ * - Analyze user navigation patterns
+ * - Monitor landing page performance
+ *
+ * @metrics
+ * - Total page views
+ * - Unique page views
+ * - Average time on page
+ * - Bounce rate by page
+ * - Scroll depth distribution
+ * - Entry/exit page analysis
+ *
+ * @chartData
+ * - Line chart: Page views over time
+ * - Bar chart: Top pages by views
+ * - Heatmap: Scroll depth by page
+ * - Funnel: Page flow analysis
+ *
+ * @example
+ * ```typescript
+ * const pageViews = new PageViews(webId, endpoint, apiKey);
+ *
+ * // Track a page view
+ * await pageViews.track({
+ *   url: window.location.href,
+ *   path: window.location.pathname,
+ *   title: document.title,
+ *   referrer: document.referrer
+ * });
+ *
+ * // Track with scroll depth
+ * await pageViews.trackScrollDepth({
+ *   path: '/blog/article-1',
+ *   scrollDepth: 75
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+import { getWindow, getDocument, isBrowser, combineTeardowns } from "../../utils/browser";
+// ============================================================================
+// PAGE VIEWS CLASS
+// ============================================================================
+/**
+ * PageViews - Track and analyze page view events.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides comprehensive page view tracking with support for:
+ * - Basic page view events
+ * - Scroll depth tracking
+ * - Time on page measurement
+ * - Exit intent detection
+ * - Page engagement scoring
+ *
+ * @example
+ * ```typescript
+ * const pageViews = new PageViews(webId, endpoint, apiKey);
+ *
+ * // Basic page view
+ * await pageViews.track({
+ *   url: 'https://example.com/products',
+ *   path: '/products',
+ *   title: 'Our Products'
+ * });
+ * ```
+ */
+export class PageViews extends FlowGridTransport {
+    /**
+     * Tracks a page view event.
+     *
+     * @param config - Page view configuration
+     * @returns Promise resolving to the API response
+     *
+     * @example
+     * ```typescript
+     * await pageViews.track({
+     *   url: window.location.href,
+     *   path: window.location.pathname,
+     *   title: document.title
+     * });
+     * ```
+     */
+    async track(config) {
+        return await this.init("page_view", {
+            type: "page_view",
+            url: config.url,
+            path: config.path,
+            title: config.title || "",
+            referrer: config.referrer || "",
+            userId: config.userId,
+            sessionId: config.sessionId,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks scroll depth on a page.
+     *
+     * @param config - Scroll depth configuration
+     * @returns Promise resolving to the API response
+     *
+     * @example
+     * ```typescript
+     * // Track when user scrolls to 50%
+     * await pageViews.trackScrollDepth({
+     *   path: '/article/how-to-guide',
+     *   scrollDepth: 50
+     * });
+     * ```
+     */
+    async trackScrollDepth(config) {
+        return await this.init("scroll_depth", {
+            type: "scroll_depth",
+            path: config.path,
+            scrollDepth: Math.min(100, Math.max(0, config.scrollDepth)),
+            timeAtDepth: config.timeAtDepth,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks time spent on a page.
+     *
+     * @param config - Time on page configuration
+     * @returns Promise resolving to the API response
+     *
+     * @example
+     * ```typescript
+     * // Track on page unload
+     * window.addEventListener('beforeunload', () => {
+     *   pageViews.trackTimeOnPage({
+     *     path: '/pricing',
+     *     duration: 45,
+     *     engaged: true
+     *   });
+     * });
+     * ```
+     */
+    async trackTimeOnPage(config) {
+        return await this.init("time_on_page", {
+            type: "time_on_page",
+            path: config.path,
+            duration: config.duration,
+            engaged: config.engaged ?? false,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks a page exit event.
+     *
+     * @param path - Page path being exited
+     * @param duration - Time spent on page
+     * @param scrollDepth - Final scroll depth
+     * @returns Promise resolving to the API response
+     */
+    async trackExit(path, duration, scrollDepth) {
+        return await this.init("page_exit", {
+            type: "page_exit",
+            path,
+            duration,
+            scrollDepth,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Auto-track page views for both classic full-page navigations and SPA
+     * route changes (history.pushState / replaceState / popstate). Also wires
+     * scroll-depth thresholds (25/50/75/100%) and a final time-on-page event
+     * when the page is hidden or unloaded.
+     *
+     * @returns A teardown function that detaches every listener.
+     *
+     * @example
+     * ```ts
+     * const stop = fg.pageViews.client.autoTrack({ userId: "u_1" });
+     * ```
+     */
+    autoTrack(options = {}) {
+        if (!isBrowser())
+            return () => { };
+        const win = getWindow();
+        const doc = getDocument();
+        let currentPath = win.location.pathname;
+        let pageStart = Date.now();
+        let maxDepth = 0;
+        const sentDepths = new Set();
+        const fireView = () => {
+            void this.track({
+                url: win.location.href,
+                path: win.location.pathname,
+                title: doc.title,
+                referrer: doc.referrer,
+                userId: options.userId,
+                sessionId: options.sessionId,
+            });
+        };
+        const flushTimeOnPage = () => {
+            const duration = Math.round((Date.now() - pageStart) / 1000);
+            if (duration <= 0)
+                return;
+            void this.trackTimeOnPage({ path: currentPath, duration, engaged: maxDepth > 10 });
+        };
+        const onRouteChange = () => {
+            if (win.location.pathname === currentPath)
+                return;
+            flushTimeOnPage();
+            currentPath = win.location.pathname;
+            pageStart = Date.now();
+            maxDepth = 0;
+            sentDepths.clear();
+            fireView();
+        };
+        // Patch history methods so we can detect SPA route changes.
+        const origPush = win.history.pushState;
+        const origReplace = win.history.replaceState;
+        win.history.pushState = function (...args) {
+            const r = origPush.apply(this, args);
+            win.dispatchEvent(new Event("flowgrid:locationchange"));
+            return r;
+        };
+        win.history.replaceState = function (...args) {
+            const r = origReplace.apply(this, args);
+            win.dispatchEvent(new Event("flowgrid:locationchange"));
+            return r;
+        };
+        const popHandler = () => onRouteChange();
+        const locHandler = () => onRouteChange();
+        win.addEventListener("popstate", popHandler);
+        win.addEventListener("flowgrid:locationchange", locHandler);
+        // Scroll-depth thresholds.
+        const onScroll = () => {
+            const docEl = doc.documentElement;
+            const scrollTop = win.scrollY || docEl.scrollTop;
+            const height = Math.max(1, docEl.scrollHeight - win.innerHeight);
+            const depth = Math.min(100, Math.round((scrollTop / height) * 100));
+            if (depth > maxDepth)
+                maxDepth = depth;
+            for (const t of [25, 50, 75, 100]) {
+                if (depth >= t && !sentDepths.has(t)) {
+                    sentDepths.add(t);
+                    void this.trackScrollDepth({ path: currentPath, scrollDepth: t });
+                }
+            }
+        };
+        win.addEventListener("scroll", onScroll, { passive: true });
+        // Flush on unload / visibility change.
+        const onHide = () => { if (doc.visibilityState === "hidden")
+            flushTimeOnPage(); };
+        doc.addEventListener("visibilitychange", onHide);
+        win.addEventListener("pagehide", flushTimeOnPage);
+        // Initial view.
+        fireView();
+        return combineTeardowns(() => win.removeEventListener("popstate", popHandler), () => win.removeEventListener("flowgrid:locationchange", locHandler), () => win.removeEventListener("scroll", onScroll), () => doc.removeEventListener("visibilitychange", onHide), () => win.removeEventListener("pagehide", flushTimeOnPage), () => { win.history.pushState = origPush; win.history.replaceState = origReplace; });
+    }
+}
+export default PageViews;
+//# sourceMappingURL=page-views.js.map

package/dist/lib/features/analytics/page-views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-views.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/page-views.ts"],"names":[],"mappings":"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"}

package/dist/lib/features/analytics/performance.d.ts

@@ -40,7 +40,8 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { DateRangeFilter, TimeSeriesData } from "../../types";
+import { TimeSeriesData } from "../../types";
+import { Teardown } from "../../utils/browser";
 /**
  * Core Web Vitals data.
  */
@@ -213,10 +214,6 @@ export interface PerformanceAnalyticsData {
  *     pageUrl: window.location.pathname
  *   });
  * });
- *
- * // Get performance report
- * const report = await performance.getAnalytics({ range: 'last7days' });
- * console.log(`Performance Score: ${report.performanceScore}`);
  * ```
  */
 export declare class PerformanceTracking extends FlowGridTransport {
@@ -252,30 +249,27 @@ export declare class PerformanceTracking extends FlowGridTransport {
      */
     trackApiCall(endpoint: string, duration: number, success: boolean, statusCode?: number): Promise<PerformanceResponse>;
     /**
-     * Gets performance analytics for dashboards.
+     * Auto-collect Core Web Vitals, navigation timing, and resource timing
+     * directly from the browser. Safe no-op outside the browser.
      *
-     * @param filter - Date range filter
-     * @returns Promise resolving to performance analytics
+     * @param options.userId       Optional user identifier attached to every metric.
+     * @param options.resources    When true, also subscribes to PerformanceObserver
+     *                             for `resource` entries. Default: false (noisy).
+     * @param options.minDuration  Only forward resources slower than this (ms). Default 200.
+     * @returns A teardown function that detaches all observers/listeners.
      *
      * @example
-     * ```typescript
-     * const analytics = await performance.getAnalytics({
-     *   range: 'last7days'
-     * });
-     *
-     * // Gauge - performance score
-     * const score = analytics.performanceScore;
-     *
-     * // Line chart - LCP trend
-     * const lcpTrend = analytics.trends.lcp.data;
-     *
-     * // Table - slowest pages
-     * const slowPages = analytics.byPage.sort((a, b) =>
-     *   b.avgLoadTime - a.avgLoadTime
-     * );
+     * ```ts
+     * const stop = fg.performance.client.autoTrack({ userId: "u_1" });
+     * // ...later
+     * stop();
      * ```
      */
-    getAnalytics(filter?: DateRangeFilter): Promise<PerformanceAnalyticsData>;
+    autoTrack(options?: {
+        userId?: string;
+        resources?: boolean;
+        minDuration?: number;
+    }): Teardown;
 }
 export { PerformanceTracking as Performance };
 export default PerformanceTracking;

package/dist/lib/features/analytics/performance.js

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview Product Analytics - Performance Monitoring
+ * @module features/analytics/performance
+ *
+ * @description
+ * Track web performance metrics including Core Web Vitals,
+ * page load times, and resource performance.
+ *
+ * @useCases
+ * - Monitor Core Web Vitals (LCP, FID, CLS)
+ * - Track page load performance
+ * - Identify slow pages and resources
+ * - Correlate performance with conversions
+ * - Monitor API response times
+ *
+ * @metrics
+ * - Largest Contentful Paint (LCP)
+ * - First Input Delay (FID)
+ * - Cumulative Layout Shift (CLS)
+ * - Time to First Byte (TTFB)
+ * - First Contentful Paint (FCP)
+ *
+ * @chartData
+ * - Line chart: Core Web Vitals over time
+ * - Bar chart: Slowest pages
+ * - Histogram: Load time distribution
+ * - Gauge: Performance score
+ *
+ * @example
+ * ```typescript
+ * const performance = new Performance(webId, endpoint, apiKey);
+ *
+ * // Track Core Web Vitals
+ * await performance.trackWebVitals({
+ *   lcp: 2500,
+ *   fid: 100,
+ *   cls: 0.1,
+ *   pageUrl: '/products'
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+import { getWindow, isBrowser, combineTeardowns } from "../../utils/browser";
+// ============================================================================
+// PERFORMANCE CLASS
+// ============================================================================
+/**
+ * Performance - Track web performance metrics.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides performance monitoring including:
+ * - Core Web Vitals tracking
+ * - Page load timing
+ * - Resource performance
+ * - API response times
+ * - Performance scoring
+ *
+ * @example
+ * ```typescript
+ * const performance = new Performance(webId, endpoint, apiKey);
+ *
+ * // Track Web Vitals (use web-vitals library)
+ * import { onLCP, onFID, onCLS } from 'web-vitals';
+ *
+ * onLCP((metric) => {
+ *   performance.trackWebVitals({
+ *     lcp: metric.value,
+ *     pageUrl: window.location.pathname
+ *   });
+ * });
+ * ```
+ */
+export class PerformanceTracking extends FlowGridTransport {
+    /**
+     * Tracks Core Web Vitals.
+     *
+     * @param data - Web Vitals data
+     * @returns Promise resolving to performance response
+     */
+    async trackWebVitals(data) {
+        return await this.init("web_vitals", {
+            type: "web_vitals",
+            ...data,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks page load timing.
+     *
+     * @param data - Page load data
+     * @returns Promise resolving to performance response
+     */
+    async trackPageLoad(data) {
+        return await this.init("page_load", {
+            type: "page_load",
+            ...data,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks resource performance.
+     *
+     * @param data - Resource data
+     * @returns Promise resolving to performance response
+     */
+    async trackResource(data) {
+        return await this.init("resource_timing", {
+            type: "resource_timing",
+            ...data,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks API call performance.
+     *
+     * @param endpoint - API endpoint
+     * @param duration - Response time (ms)
+     * @param success - Whether call succeeded
+     * @param statusCode - HTTP status code
+     * @returns Promise resolving to performance response
+     */
+    async trackApiCall(endpoint, duration, success, statusCode) {
+        return await this.init("api_timing", {
+            type: "api_timing",
+            endpoint,
+            duration,
+            success,
+            statusCode,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Auto-collect Core Web Vitals, navigation timing, and resource timing
+     * directly from the browser. Safe no-op outside the browser.
+     *
+     * @param options.userId       Optional user identifier attached to every metric.
+     * @param options.resources    When true, also subscribes to PerformanceObserver
+     *                             for `resource` entries. Default: false (noisy).
+     * @param options.minDuration  Only forward resources slower than this (ms). Default 200.
+     * @returns A teardown function that detaches all observers/listeners.
+     *
+     * @example
+     * ```ts
+     * const stop = fg.performance.client.autoTrack({ userId: "u_1" });
+     * // ...later
+     * stop();
+     * ```
+     */
+    autoTrack(options = {}) {
+        if (!isBrowser())
+            return () => { };
+        const win = getWindow();
+        const pageUrl = win.location.pathname;
+        const teardowns = [];
+        // --- Web Vitals via the `web-vitals` library (dynamic import keeps it
+        //     out of server bundles even if tree-shaking misses it).
+        let cancelled = false;
+        void import("web-vitals").then((wv) => {
+            if (cancelled)
+                return;
+            const send = (metric) => {
+                const key = metric.name.toLowerCase();
+                const payload = { pageUrl, userId: options.userId };
+                payload[key] = metric.value;
+                void this.trackWebVitals(payload);
+            };
+            wv.onLCP?.(send);
+            wv.onCLS?.(send);
+            wv.onINP?.(send);
+            wv.onFCP?.(send);
+            wv.onTTFB?.(send);
+            // FID was removed in web-vitals v4+, but we still surface it if present
+            wv.onFID?.(send);
+        }).catch(() => { });
+        teardowns.push(() => { cancelled = true; });
+        // --- PerformanceNavigationTiming → trackPageLoad
+        const reportNavigation = () => {
+            const nav = win.performance?.getEntriesByType?.("navigation")?.[0];
+            if (!nav)
+                return;
+            void this.trackPageLoad({
+                pageUrl,
+                dnsTime: Math.max(0, nav.domainLookupEnd - nav.domainLookupStart),
+                tcpTime: Math.max(0, nav.connectEnd - nav.connectStart),
+                ttfb: Math.max(0, nav.responseStart - nav.requestStart),
+                domContentLoaded: nav.domContentLoadedEventEnd,
+                loadTime: nav.loadEventEnd,
+                domInteractive: nav.domInteractive,
+                transferSize: nav.transferSize,
+            });
+        };
+        if (win.document.readyState === "complete") {
+            reportNavigation();
+        }
+        else {
+            const onLoad = () => reportNavigation();
+            win.addEventListener("load", onLoad, { once: true });
+            teardowns.push(() => win.removeEventListener("load", onLoad));
+        }
+        // --- Resource timing (opt-in)
+        if (options.resources && typeof win.PerformanceObserver === "function") {
+            const min = options.minDuration ?? 200;
+            const obs = new win.PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    if (entry.duration < min)
+                        continue;
+                    const initiator = entry.initiatorType;
+                    void this.trackResource({
+                        resourceUrl: entry.name,
+                        resourceType: ([
+                            "script", "stylesheet", "image", "font", "fetch", "xhr",
+                        ].includes(initiator) ? initiator : "other"),
+                        duration: Math.round(entry.duration),
+                        transferSize: entry.transferSize,
+                        pageUrl,
+                    });
+                }
+            });
+            try {
+                obs.observe({ type: "resource", buffered: true });
+                teardowns.push(() => obs.disconnect());
+            }
+            catch { /* unsupported */ }
+        }
+        return combineTeardowns(...teardowns);
+    }
+}
+export { PerformanceTracking as Performance };
+export default PerformanceTracking;
+//# sourceMappingURL=performance.js.map

package/dist/lib/features/analytics/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/performance.ts"],"names":[],"mappings":"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"}