flowgrid-sdk 1.2.0 → 1.3.0

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

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Product Analytics - Heatmaps & Click Tracking
+ * @module features/analytics/heatmaps
+ *
+ * @description
+ * Track user interactions for heatmap visualization including
+ * clicks, mouse movements, and scroll behavior.
+ *
+ * @useCases
+ * - Visualize click patterns on pages
+ * - Identify dead zones and ignored elements
+ * - Analyze scroll depth and attention
+ * - Optimize CTA placement
+ * - Improve page layout based on behavior
+ *
+ * @metrics
+ * - Click coordinates and density
+ * - Scroll depth distribution
+ * - Attention time by viewport
+ * - Element interaction rates
+ * - Rage clicks detection
+ *
+ * @chartData
+ * - Heatmap: Click density overlay
+ * - Scroll map: Attention by page section
+ * - Element report: Interaction by element
+ * - Rage click detection
+ *
+ * @example
+ * ```typescript
+ * const heatmaps = new Heatmaps(webId, endpoint, apiKey);
+ *
+ * // Track click
+ * await heatmaps.trackClick({
+ *   pageUrl: '/pricing',
+ *   x: 450,
+ *   y: 320,
+ *   viewportWidth: 1920,
+ *   viewportHeight: 1080
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+import { getWindow, getDocument, isBrowser, combineTeardowns } from "../../utils/browser";
+// ============================================================================
+// HEATMAPS CLASS
+// ============================================================================
+/**
+ * Heatmaps - Track user interactions for heatmap visualization.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides heatmap data collection including:
+ * - Click tracking with coordinates
+ * - Mouse movement tracking
+ * - Scroll depth tracking
+ * - Element interaction tracking
+ * - Rage click detection
+ *
+ * @example
+ * ```typescript
+ * const heatmaps = new Heatmaps(webId, endpoint, apiKey);
+ *
+ * // Track clicks
+ * document.addEventListener('click', (e) => {
+ *   heatmaps.trackClick({
+ *     pageUrl: window.location.pathname,
+ *     x: e.clientX,
+ *     y: e.clientY + window.scrollY,
+ *     viewportWidth: window.innerWidth,
+ *     viewportHeight: window.innerHeight,
+ *     elementSelector: getSelector(e.target)
+ *   });
+ * });
+ *
+ * // Get heatmap data for visualization
+ * const data = await heatmaps.getData('/pricing', { range: 'last7days' });
+ * ```
+ */
+export class Heatmaps extends FlowGridTransport {
+    constructor() {
+        super(...arguments);
+        /** Throttle timestamps */
+        this.lastMovementTime = 0;
+        this.lastScrollTime = 0;
+    }
+    /**
+     * Tracks a click interaction.
+     *
+     * @param data - Click data
+     * @returns Promise resolving to heatmap response
+     */
+    async trackClick(data) {
+        return await this.init("heatmap_click", {
+            type: "heatmap_click",
+            pageUrl: data.pageUrl,
+            x: data.x,
+            y: data.y,
+            normalizedX: data.x / data.viewportWidth,
+            normalizedY: data.y / data.viewportHeight,
+            viewportWidth: data.viewportWidth,
+            viewportHeight: data.viewportHeight,
+            elementSelector: data.elementSelector,
+            elementText: data.elementText?.substring(0, 50),
+            userId: data.userId,
+            sessionId: data.sessionId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks mouse movement path.
+     *
+     * @param data - Movement data
+     * @returns Promise resolving to heatmap response
+     */
+    async trackMovement(data) {
+        const now = Date.now();
+        if (now - this.lastMovementTime < Heatmaps.MOVEMENT_THROTTLE_MS) {
+            return { eventName: 'heatmap_movement', properties: {}, response: { recorded: false, interactionId: '' }, timestamp: new Date().toISOString() };
+        }
+        this.lastMovementTime = now;
+        return await this.init("heatmap_movement", {
+            type: "heatmap_movement",
+            pageUrl: data.pageUrl,
+            path: data.path,
+            viewport: data.viewport,
+            sessionId: data.sessionId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks scroll behavior.
+     *
+     * @param data - Scroll data
+     * @returns Promise resolving to heatmap response
+     */
+    async trackScroll(data) {
+        const now = Date.now();
+        if (now - this.lastScrollTime < Heatmaps.SCROLL_THROTTLE_MS) {
+            return { eventName: 'heatmap_scroll', properties: {}, response: { recorded: false, interactionId: '' }, timestamp: new Date().toISOString() };
+        }
+        this.lastScrollTime = now;
+        return await this.init("heatmap_scroll", {
+            type: "heatmap_scroll",
+            pageUrl: data.pageUrl,
+            maxScrollDepth: data.maxScrollDepth,
+            pageHeight: data.pageHeight,
+            viewportHeight: data.viewportHeight,
+            timeAtDepths: data.timeAtDepths,
+            sessionId: data.sessionId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks rage clicks (repeated clicks in frustration).
+     *
+     * @param pageUrl - Page URL
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     * @param clickCount - Number of rapid clicks
+     * @returns Promise resolving to heatmap response
+     */
+    async trackRageClick(pageUrl, x, y, clickCount) {
+        return await this.init("heatmap_rage_click", {
+            type: "heatmap_rage_click",
+            pageUrl,
+            x,
+            y,
+            clickCount,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Auto-collect heatmap interactions: clicks (with element selector + text)
+     * and scroll depth on the current page. Mouse-move tracking is opt-in
+     * because the volume can be very high.
+     *
+     * @param options.movement Subscribe to throttled mousemove sampling.
+     * @param options.userId   Attached to every event.
+     * @returns Teardown function detaching all listeners.
+     */
+    autoTrack(options = {}) {
+        if (!isBrowser())
+            return () => { };
+        const win = getWindow();
+        const doc = getDocument();
+        const selectorOf = (el) => {
+            if (!el)
+                return "";
+            if (el.id)
+                return `#${el.id}`;
+            const tag = el.tagName.toLowerCase();
+            const cls = (el.className && typeof el.className === "string")
+                ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".")
+                : "";
+            return `${tag}${cls}`;
+        };
+        const onClick = (e) => {
+            const target = e.target;
+            void this.trackClick({
+                pageUrl: win.location.pathname,
+                x: e.clientX,
+                y: e.clientY + win.scrollY,
+                viewportWidth: win.innerWidth,
+                viewportHeight: win.innerHeight,
+                elementSelector: selectorOf(target),
+                elementText: (target?.textContent || "").trim().slice(0, 50),
+                userId: options.userId,
+                sessionId: options.sessionId,
+            });
+        };
+        doc.addEventListener("click", onClick, { capture: true, passive: true });
+        let maxDepth = 0;
+        const onScroll = () => {
+            const docEl = doc.documentElement;
+            const top = win.scrollY || docEl.scrollTop;
+            const height = Math.max(1, docEl.scrollHeight - win.innerHeight);
+            const depth = Math.min(100, Math.round((top / height) * 100));
+            if (depth > maxDepth)
+                maxDepth = depth;
+            void this.trackScroll({
+                pageUrl: win.location.pathname,
+                maxScrollDepth: maxDepth,
+                pageHeight: docEl.scrollHeight,
+                viewportHeight: win.innerHeight,
+                sessionId: options.sessionId,
+            });
+        };
+        win.addEventListener("scroll", onScroll, { passive: true });
+        let moveTeardown;
+        if (options.movement) {
+            let buffer = [];
+            const start = Date.now();
+            const onMove = (e) => {
+                buffer.push({ x: e.clientX, y: e.clientY, t: Date.now() - start });
+                if (buffer.length >= 50) {
+                    const path = buffer;
+                    buffer = [];
+                    void this.trackMovement({
+                        pageUrl: win.location.pathname,
+                        path,
+                        viewport: { width: win.innerWidth, height: win.innerHeight },
+                        sessionId: options.sessionId,
+                    });
+                }
+            };
+            doc.addEventListener("mousemove", onMove, { passive: true });
+            moveTeardown = () => doc.removeEventListener("mousemove", onMove);
+        }
+        return combineTeardowns(() => doc.removeEventListener("click", onClick, { capture: true }), () => win.removeEventListener("scroll", onScroll), moveTeardown);
+    }
+}
+/** Throttle intervals (ms) */
+Heatmaps.MOVEMENT_THROTTLE_MS = 100;
+Heatmaps.SCROLL_THROTTLE_MS = 500;
+export default Heatmaps;
+//# sourceMappingURL=heatmaps.js.map

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

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

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

@@ -43,7 +43,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { UserTraits, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+import { UserTraits, MoneyValue, TimeSeriesData } from "../../types";
 /**
  * Configuration for identifying a user.
  */
@@ -249,25 +249,5 @@ export declare class Identify extends FlowGridTransport {
      * @returns Promise resolving to reset response
      */
     reset(userId: string): Promise<IdentifyResponse>;
-    /**
-     * Retrieves user analytics data for dashboards and charts.
-     *
-     * @param filter - Date range filter
-     * @returns Promise resolving to user analytics
-     *
-     * @example
-     * ```typescript
-     * const analytics = await identify.getAnalytics({
-     *   range: 'last30days'
-     * });
-     *
-     * // Pie chart - users by plan
-     * const planData = analytics.byPlan.map(p => ({
-     *   name: p.plan,
-     *   value: p.count
-     * }));
-     * ```
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<UserAnalyticsData>;
 }
 export default Identify;

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

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Product Analytics - User Identification & Traits
+ * @module features/analytics/identify
+ *
+ * @description
+ * Identify users and track their traits for personalization,
+ * segmentation, and cohort analysis.
+ *
+ * @useCases
+ * - Link anonymous sessions to authenticated users
+ * - Store user profile data for segmentation
+ * - Track user lifecycle changes (signup, upgrade, churn)
+ * - Enable personalized experiences
+ * - Build user cohorts for analysis
+ *
+ * @metrics
+ * - Total identified users
+ * - Anonymous to identified conversion rate
+ * - Users by plan/segment
+ * - User lifetime value distribution
+ * - Trait distribution
+ *
+ * @chartData
+ * - Pie chart: Users by plan
+ * - Bar chart: Users by trait value
+ * - Line chart: New identifications over time
+ * - Table: User segments
+ *
+ * @example
+ * ```typescript
+ * const identify = new Identify(webId, endpoint, apiKey);
+ *
+ * // Identify user on login
+ * await identify.user({
+ *   userId: 'user_123',
+ *   traits: {
+ *     email: 'user@example.com',
+ *     name: 'John Doe',
+ *     plan: 'premium',
+ *     createdAt: '2025-01-15'
+ *   }
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// IDENTIFY CLASS
+// ============================================================================
+/**
+ * Identify - User identification and trait management.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides user identification capabilities including:
+ * - User identification on login/signup
+ * - Anonymous to identified user linking
+ * - User trait/property storage
+ * - User aliasing for ID changes
+ * - Group/company association
+ *
+ * @example
+ * ```typescript
+ * const identify = new Identify(webId, endpoint, apiKey);
+ *
+ * // On user signup
+ * await identify.user({
+ *   userId: 'user_123',
+ *   anonymousId: getAnonymousId(),
+ *   traits: {
+ *     email: 'user@example.com',
+ *     name: 'Jane Smith',
+ *     plan: 'starter',
+ *     createdAt: new Date().toISOString()
+ *   }
+ * });
+ *
+ * // Associate user with company
+ * await identify.group({
+ *   userId: 'user_123',
+ *   groupId: 'company_456',
+ *   traits: { name: 'Acme Inc', employees: 50 }
+ * });
+ * ```
+ */
+export class Identify extends FlowGridTransport {
+    /**
+     * Identifies a user with traits.
+     *
+     * @param config - Identification configuration
+     * @returns Promise resolving to identify response
+     *
+     * @example
+     * ```typescript
+     * // Basic identification
+     * await identify.user({
+     *   userId: 'user_123',
+     *   traits: { email: 'user@example.com' }
+     * });
+     *
+     * // With anonymous ID linking
+     * await identify.user({
+     *   userId: 'user_123',
+     *   anonymousId: localStorage.getItem('anonId'),
+     *   traits: {
+     *     name: 'John Doe',
+     *     plan: 'premium',
+     *     ltv: { amount: 29900, currency: 'USD' }
+     *   }
+     * });
+     * ```
+     */
+    async user(config) {
+        return await this.init("identify_user", {
+            type: "identify",
+            userId: config.userId,
+            anonymousId: config.anonymousId,
+            traits: config.traits || {},
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Updates traits for an existing user.
+     *
+     * @param userId - User identifier
+     * @param traits - Traits to update/add
+     * @returns Promise resolving to identify response
+     *
+     * @example
+     * ```typescript
+     * // Update user plan after upgrade
+     * await identify.updateTraits('user_123', {
+     *   plan: 'enterprise',
+     *   ltv: { amount: 99900, currency: 'USD' }
+     * });
+     * ```
+     */
+    async updateTraits(userId, traits) {
+        return await this.init("update_traits", {
+            type: "update_traits",
+            userId,
+            traits,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Creates an alias between two user IDs.
+     *
+     * @param config - Alias configuration
+     * @returns Promise resolving to alias response
+     *
+     * @example
+     * ```typescript
+     * // When user ID changes (e.g., after migration)
+     * await identify.alias({
+     *   previousId: 'old_user_id',
+     *   userId: 'new_user_id'
+     * });
+     * ```
+     */
+    async alias(config) {
+        return await this.init("alias_user", {
+            type: "alias",
+            previousId: config.previousId,
+            userId: config.userId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Associates a user with a group/company.
+     *
+     * @param config - Group configuration
+     * @returns Promise resolving to group response
+     *
+     * @example
+     * ```typescript
+     * await identify.group({
+     *   userId: 'user_123',
+     *   groupId: 'company_456',
+     *   traits: {
+     *     name: 'Acme Corporation',
+     *     industry: 'Technology',
+     *     employees: 500,
+     *     plan: 'enterprise'
+     *   }
+     * });
+     * ```
+     */
+    async group(config) {
+        return await this.init("group_user", {
+            type: "group",
+            userId: config.userId,
+            groupId: config.groupId,
+            traits: config.traits || {},
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Resets user identity (logout).
+     *
+     * @param userId - User ID to reset
+     * @returns Promise resolving to reset response
+     */
+    async reset(userId) {
+        return await this.init("reset_identity", {
+            type: "reset",
+            userId,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Identify;
+//# sourceMappingURL=identify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identify.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/identify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAkG3D,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,OAAO,QAAS,SAAQ,iBAAiB;IAC7C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,IAAI,CAAC,MAAsB;QAC/B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,YAAY,CAAC,MAAc,EAAE,MAAkB;QACnD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,eAAe;YACrB,MAAM;YACN,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC7B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE;YACnC,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC7B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE;YACnC,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc;QACxB,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE;YACvC,IAAI,EAAE,OAAO;YACb,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAED,eAAe,QAAQ,CAAC"}

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

@@ -11,6 +11,8 @@ export { Retention } from './retention';
 export { Attribution } from './attribution';
 export { Heatmaps } from './heatmaps';
 export { PerformanceTracking, PerformanceTracking as Performance } from './performance';
+export { SessionReplay } from './replay';
+export type { ReplayPrivacyMetadata, SessionReplayDropMetadata, SessionReplayErrorContext, SessionReplayFlushMetadata, SessionReplayFlushReason, SessionReplayOptions, SessionReplaySendChunkOptions, SessionReplayState, SessionReplayStatus, } from './replay';
 export type { PageViewConfig, ScrollDepthConfig, TimeOnPageConfig, PageViewResponse, PageAnalyticsData } from './page-views';
 export type { SessionStartConfig, SessionResponse, SessionEndResponse, SessionAnalyticsData, RealTimeSessionData } from './sessions';
 export type { EventTrackConfig, BatchEventConfig, EventResponse, BatchEventResponse, EventAnalyticsData } from './events';

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

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Analytics features barrel export
+ * @module features/analytics
+ */
+export { PageViews } from './page-views';
+export { Sessions } from './sessions';
+export { Events } from './events';
+export { Identify } from './identify';
+export { Funnels } from './funnels';
+export { Retention } from './retention';
+export { Attribution } from './attribution';
+export { Heatmaps } from './heatmaps';
+export { PerformanceTracking, PerformanceTracking as Performance } from './performance';
+export { SessionReplay } from './replay';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/features/analytics/page-views.d.ts

@@ -47,7 +47,8 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { TimeSeriesData, DateRangeFilter, PaginationParams } from "../../types";
+import { Teardown } from "../../utils/browser";
+import { TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking a page view.
  */
@@ -148,17 +149,6 @@ export interface PageAnalyticsData {
  *   path: '/products',
  *   title: 'Our Products'
  * });
- *
- * // Pull analytics data for charts
- * const analytics = await pageViews.getAnalytics({
- *   range: 'last30days'
- * });
- *
- * // Data ready for charting
- * const chartData = analytics.timeSeries.data.map(d => ({
- *   x: d.label,
- *   y: d.value
- * }));
  * ```
  */
 export declare class PageViews extends FlowGridTransport {
@@ -223,28 +213,21 @@ export declare class PageViews extends FlowGridTransport {
      */
     trackExit(path: string, duration: number, scrollDepth: number): Promise<PageViewResponse>;
     /**
-     * Retrieves page analytics data for dashboards and charts.
+     * 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.
      *
-     * @param filter - Date range filter
-     * @param pagination - Pagination options
-     * @returns Promise resolving to analytics data
+     * @returns A teardown function that detaches every listener.
      *
      * @example
-     * ```typescript
-     * const analytics = await pageViews.getAnalytics({
-     *   range: 'last7days'
-     * });
-     *
-     * // Use for line chart
-     * const lineData = analytics.timeSeries.data;
-     *
-     * // Use for bar chart
-     * const barData = analytics.topPages.map(p => ({
-     *   label: p.path,
-     *   value: p.views
-     * }));
+     * ```ts
+     * const stop = fg.pageViews.client.autoTrack({ userId: "u_1" });
      * ```
      */
-    getAnalytics(filter?: DateRangeFilter, pagination?: PaginationParams): Promise<PageAnalyticsData>;
+    autoTrack(options?: {
+        userId?: string;
+        sessionId?: string;
+    }): Teardown;
 }
 export default PageViews;