flowgrid-sdk 1.0.0

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

@@ -0,0 +1,247 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter } from "../../types";
+/**
+ * Click interaction data.
+ */
+export interface ClickData {
+    /** Page URL */
+    pageUrl: string;
+    /** X coordinate (from left) */
+    x: number;
+    /** Y coordinate (from top) */
+    y: number;
+    /** Viewport width */
+    viewportWidth: number;
+    /** Viewport height */
+    viewportHeight: number;
+    /** Element selector clicked */
+    elementSelector?: string;
+    /** Element text (truncated) */
+    elementText?: string;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Movement/hover data.
+ */
+export interface MovementData {
+    /** Page URL */
+    pageUrl: string;
+    /** Movement path (array of x,y coordinates) */
+    path: Array<{
+        x: number;
+        y: number;
+        t: number;
+    }>;
+    /** Viewport dimensions */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Scroll data.
+ */
+export interface ScrollData {
+    /** Page URL */
+    pageUrl: string;
+    /** Maximum scroll depth reached (percentage) */
+    maxScrollDepth: number;
+    /** Page height */
+    pageHeight: number;
+    /** Viewport height */
+    viewportHeight: number;
+    /** Time at various scroll depths */
+    timeAtDepths?: Record<number, number>;
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Heatmap response from API.
+ */
+export interface HeatmapResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        recorded: boolean;
+        interactionId: string;
+    };
+    timestamp: string;
+}
+/**
+ * Heatmap data for visualization.
+ */
+export interface HeatmapData {
+    /** Page URL */
+    pageUrl: string;
+    /** Click points for heatmap */
+    clicks: Array<{
+        x: number;
+        y: number;
+        count: number;
+        normalizedX: number;
+        normalizedY: number;
+    }>;
+    /** Scroll depth data */
+    scrollDepth: Array<{
+        depth: number;
+        usersReached: number;
+        percentageReached: number;
+        avgTimeAtDepth: number;
+    }>;
+    /** Element interaction data */
+    elements: Array<{
+        selector: string;
+        clicks: number;
+        hovers: number;
+        avgTimeHovered: number;
+    }>;
+    /** Rage click zones */
+    rageClicks: Array<{
+        x: number;
+        y: number;
+        count: number;
+        element: string;
+    }>;
+    /** Summary */
+    summary: {
+        totalClicks: number;
+        uniqueSessions: number;
+        avgScrollDepth: number;
+        rageClickRate: number;
+    };
+}
+/**
+ * Heatmaps - Track user interactions for heatmap visualization.
+ *
+ * @extends FTRPC
+ *
+ * @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 declare class Heatmaps extends FTRPC {
+    /**
+     * Tracks a click interaction.
+     *
+     * @param data - Click data
+     * @returns Promise resolving to heatmap response
+     */
+    trackClick(data: ClickData): Promise<HeatmapResponse>;
+    /**
+     * Tracks mouse movement path.
+     *
+     * @param data - Movement data
+     * @returns Promise resolving to heatmap response
+     */
+    trackMovement(data: MovementData): Promise<HeatmapResponse>;
+    /**
+     * Tracks scroll behavior.
+     *
+     * @param data - Scroll data
+     * @returns Promise resolving to heatmap response
+     */
+    trackScroll(data: ScrollData): Promise<HeatmapResponse>;
+    /**
+     * 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
+     */
+    trackRageClick(pageUrl: string, x: number, y: number, clickCount: number): Promise<HeatmapResponse>;
+    /**
+     * Gets heatmap data for visualization.
+     *
+     * @param pageUrl - Page URL to get data for
+     * @param filter - Date range filter
+     * @returns Promise resolving to heatmap data
+     *
+     * @example
+     * ```typescript
+     * const data = await heatmaps.getData('/pricing', {
+     *   range: 'last7days'
+     * });
+     *
+     * // Render click heatmap
+     * renderHeatmap(data.clicks);
+     *
+     * // Render scroll map
+     * renderScrollMap(data.scrollDepth);
+     * ```
+     */
+    getData(pageUrl: string, filter?: DateRangeFilter): Promise<HeatmapData>;
+}
+export default Heatmaps;

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

@@ -0,0 +1,273 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { UserTraits, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Configuration for identifying a user.
+ */
+export interface IdentifyConfig {
+    /** Unique user identifier */
+    userId: string;
+    /** Anonymous ID to link (optional) */
+    anonymousId?: string;
+    /** User traits/properties */
+    traits?: UserTraits;
+}
+/**
+ * Configuration for aliasing user IDs.
+ */
+export interface AliasConfig {
+    /** Previous user ID */
+    previousId: string;
+    /** New user ID */
+    userId: string;
+}
+/**
+ * Configuration for grouping users.
+ */
+export interface GroupConfig {
+    /** User ID */
+    userId: string;
+    /** Group/company ID */
+    groupId: string;
+    /** Group traits */
+    traits?: {
+        name?: string;
+        industry?: string;
+        employees?: number;
+        plan?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Identify response from API.
+ */
+export interface IdentifyResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        userId: string;
+        identified: boolean;
+        isNewUser: boolean;
+        linkedAnonymousId?: string;
+    };
+    timestamp: string;
+}
+/**
+ * User analytics data for charts.
+ */
+export interface UserAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalUsers: number;
+        identifiedUsers: number;
+        anonymousUsers: number;
+        newUsersThisPeriod: number;
+        identificationRate: number;
+    };
+    /** Users by plan/segment */
+    byPlan: Array<{
+        plan: string;
+        count: number;
+        percentage: number;
+        mrr?: MoneyValue;
+    }>;
+    /** New users time series */
+    newUsersTimeSeries: TimeSeriesData;
+    /** User lifecycle distribution */
+    byLifecycleStage: Array<{
+        stage: string;
+        count: number;
+        percentage: number;
+    }>;
+}
+/**
+ * Identify - User identification and trait management.
+ *
+ * @extends FTRPC
+ *
+ * @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 declare class Identify extends FTRPC {
+    /**
+     * 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' }
+     *   }
+     * });
+     * ```
+     */
+    user(config: IdentifyConfig): Promise<IdentifyResponse>;
+    /**
+     * 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' }
+     * });
+     * ```
+     */
+    updateTraits(userId: string, traits: UserTraits): Promise<IdentifyResponse>;
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    alias(config: AliasConfig): Promise<IdentifyResponse>;
+    /**
+     * 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'
+     *   }
+     * });
+     * ```
+     */
+    group(config: GroupConfig): Promise<IdentifyResponse>;
+    /**
+     * Resets user identity (logout).
+     *
+     * @param userId - User ID to reset
+     * @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/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 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';
+export type { IdentifyConfig, AliasConfig, GroupConfig, IdentifyResponse, UserAnalyticsData } from './identify';
+export type { FunnelDefinition, FunnelStepConfig, FunnelStepResponse, FunnelAnalyticsData, FunnelComparisonData } from './funnels';
+export type { ActivityConfig, CohortAnalysisConfig, ActivityResponse, CohortAnalysisData, StickinessData, ChurnAnalysisData } from './retention';
+export type { AttributionModel, TouchpointConfig, ConversionEvent, TouchpointResponse, AttributionReportData } from './attribution';
+export type { ClickData, MovementData, ScrollData, HeatmapResponse, HeatmapData } from './heatmaps';
+export type { WebVitalsData, PageLoadData, ResourceData, PerformanceResponse, PerformanceAnalyticsData } from './performance';