flowgrid-sdk 1.0.0

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

@@ -0,0 +1,250 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { TimeSeriesData, DateRangeFilter, PaginationParams } from "../../types";
+/**
+ * Configuration for tracking a page view.
+ */
+export interface PageViewConfig {
+    /** Full page URL */
+    url: string;
+    /** Page path (without domain) */
+    path: string;
+    /** Page title */
+    title?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** User ID (if authenticated) */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for tracking scroll depth.
+ */
+export interface ScrollDepthConfig {
+    /** Page path */
+    path: string;
+    /** Scroll depth percentage (0-100) */
+    scrollDepth: number;
+    /** Time at this depth (seconds) */
+    timeAtDepth?: number;
+}
+/**
+ * Configuration for tracking time on page.
+ */
+export interface TimeOnPageConfig {
+    /** Page path */
+    path: string;
+    /** Time spent in seconds */
+    duration: number;
+    /** Whether user engaged (scrolled, clicked, etc.) */
+    engaged?: boolean;
+}
+/**
+ * Page view response from API.
+ */
+export interface PageViewResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        pageViewId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Page analytics data for charts.
+ */
+export interface PageAnalyticsData {
+    /** Top pages */
+    topPages: Array<{
+        path: string;
+        title: string;
+        views: number;
+        uniqueViews: number;
+        avgTimeOnPage: number;
+        bounceRate: number;
+    }>;
+    /** Page views time series */
+    timeSeries: TimeSeriesData;
+    /** Summary metrics */
+    summary: {
+        totalPageViews: number;
+        uniquePageViews: number;
+        avgTimeOnPage: number;
+        avgScrollDepth: number;
+        bounceRate: number;
+    };
+}
+/**
+ * PageViews - Track and analyze page view events.
+ *
+ * @extends FTRPC
+ *
+ * @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'
+ * });
+ *
+ * // 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 FTRPC {
+    /**
+     * 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
+     * });
+     * ```
+     */
+    track(config: PageViewConfig): Promise<PageViewResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    trackScrollDepth(config: ScrollDepthConfig): Promise<PageViewResponse>;
+    /**
+     * 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
+     *   });
+     * });
+     * ```
+     */
+    trackTimeOnPage(config: TimeOnPageConfig): Promise<PageViewResponse>;
+    /**
+     * 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
+     */
+    trackExit(path: string, duration: number, scrollDepth: number): Promise<PageViewResponse>;
+    /**
+     * Retrieves page analytics data for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @param pagination - Pagination options
+     * @returns Promise resolving to analytics data
+     *
+     * @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
+     * }));
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter, pagination?: PaginationParams): Promise<PageAnalyticsData>;
+}
+export default PageViews;

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

@@ -0,0 +1,281 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Core Web Vitals data.
+ */
+export interface WebVitalsData {
+    /** Largest Contentful Paint (ms) */
+    lcp?: number;
+    /** First Input Delay (ms) */
+    fid?: number;
+    /** Cumulative Layout Shift (score) */
+    cls?: number;
+    /** First Contentful Paint (ms) */
+    fcp?: number;
+    /** Time to First Byte (ms) */
+    ttfb?: number;
+    /** Interaction to Next Paint (ms) */
+    inp?: number;
+    /** Page URL */
+    pageUrl: string;
+    /** User ID */
+    userId?: string;
+    /** Connection type */
+    connectionType?: 'slow-2g' | '2g' | '3g' | '4g' | 'wifi' | 'unknown';
+    /** Device type */
+    deviceType?: 'mobile' | 'tablet' | 'desktop';
+}
+/**
+ * Page load timing data.
+ */
+export interface PageLoadData {
+    /** Page URL */
+    pageUrl: string;
+    /** DNS lookup time (ms) */
+    dnsTime?: number;
+    /** TCP connection time (ms) */
+    tcpTime?: number;
+    /** Time to first byte (ms) */
+    ttfb?: number;
+    /** DOM content loaded time (ms) */
+    domContentLoaded?: number;
+    /** Full page load time (ms) */
+    loadTime?: number;
+    /** DOM interactive time (ms) */
+    domInteractive?: number;
+    /** Number of resources */
+    resourceCount?: number;
+    /** Total transfer size (bytes) */
+    transferSize?: number;
+}
+/**
+ * Resource timing data.
+ */
+export interface ResourceData {
+    /** Resource URL */
+    resourceUrl: string;
+    /** Resource type */
+    resourceType: 'script' | 'stylesheet' | 'image' | 'font' | 'fetch' | 'xhr' | 'other';
+    /** Duration (ms) */
+    duration: number;
+    /** Transfer size (bytes) */
+    transferSize?: number;
+    /** Page URL where resource was loaded */
+    pageUrl: string;
+}
+/**
+ * Performance response from API.
+ */
+export interface PerformanceResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        recorded: boolean;
+        performanceScore?: number;
+    };
+    timestamp: string;
+}
+/**
+ * Performance analytics data.
+ */
+export interface PerformanceAnalyticsData {
+    /** Core Web Vitals summary */
+    webVitals: {
+        lcp: {
+            p50: number;
+            p75: number;
+            p95: number;
+            good: number;
+            needsImprovement: number;
+            poor: number;
+        };
+        fid: {
+            p50: number;
+            p75: number;
+            p95: number;
+            good: number;
+            needsImprovement: number;
+            poor: number;
+        };
+        cls: {
+            p50: number;
+            p75: number;
+            p95: number;
+            good: number;
+            needsImprovement: number;
+            poor: number;
+        };
+        inp: {
+            p50: number;
+            p75: number;
+            p95: number;
+            good: number;
+            needsImprovement: number;
+            poor: number;
+        };
+    };
+    /** Performance by page */
+    byPage: Array<{
+        pageUrl: string;
+        avgLoadTime: number;
+        avgLCP: number;
+        avgFID: number;
+        avgCLS: number;
+        sampleSize: number;
+    }>;
+    /** Performance by device */
+    byDevice: Array<{
+        device: string;
+        avgLoadTime: number;
+        avgLCP: number;
+        sampleSize: number;
+    }>;
+    /** Slowest resources */
+    slowResources: Array<{
+        resourceUrl: string;
+        resourceType: string;
+        avgDuration: number;
+        occurrences: number;
+    }>;
+    /** Performance trends */
+    trends: {
+        lcp: TimeSeriesData;
+        fid: TimeSeriesData;
+        cls: TimeSeriesData;
+    };
+    /** Overall score (0-100) */
+    performanceScore: number;
+}
+/**
+ * Performance - Track web performance metrics.
+ *
+ * @extends FTRPC
+ *
+ * @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
+ *   });
+ * });
+ *
+ * // Get performance report
+ * const report = await performance.getAnalytics({ range: 'last7days' });
+ * console.log(`Performance Score: ${report.performanceScore}`);
+ * ```
+ */
+export declare class PerformanceTracking extends FTRPC {
+    /**
+     * Tracks Core Web Vitals.
+     *
+     * @param data - Web Vitals data
+     * @returns Promise resolving to performance response
+     */
+    trackWebVitals(data: WebVitalsData): Promise<PerformanceResponse>;
+    /**
+     * Tracks page load timing.
+     *
+     * @param data - Page load data
+     * @returns Promise resolving to performance response
+     */
+    trackPageLoad(data: PageLoadData): Promise<PerformanceResponse>;
+    /**
+     * Tracks resource performance.
+     *
+     * @param data - Resource data
+     * @returns Promise resolving to performance response
+     */
+    trackResource(data: ResourceData): Promise<PerformanceResponse>;
+    /**
+     * 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
+     */
+    trackApiCall(endpoint: string, duration: number, success: boolean, statusCode?: number): Promise<PerformanceResponse>;
+    /**
+     * Gets performance analytics for dashboards.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to performance analytics
+     *
+     * @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
+     * );
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<PerformanceAnalyticsData>;
+}
+export { PerformanceTracking as Performance };
+export default PerformanceTracking;