flowgrid-sdk 1.0.0

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

@@ -0,0 +1,294 @@
+/**
+ * @fileoverview Product Analytics - Retention Analysis
+ * @module features/analytics/retention
+ *
+ * @description
+ * Track and analyze user retention using cohort analysis,
+ * identify churn patterns, and measure user stickiness.
+ *
+ * @useCases
+ * - Measure week-over-week retention rates
+ * - Compare retention across user cohorts
+ * - Identify churn risk factors
+ * - Track feature adoption impact on retention
+ * - Calculate DAU/MAU ratios (stickiness)
+ *
+ * @metrics
+ * - Day 1, 7, 30 retention rates
+ * - Cohort retention curves
+ * - Churn rate by segment
+ * - User resurrection rate
+ * - DAU/WAU/MAU ratios
+ *
+ * @chartData
+ * - Retention curve: Line chart over time
+ * - Cohort matrix: Heatmap by cohort/period
+ * - Bar chart: Retention by segment
+ * - Trend line: Stickiness over time
+ *
+ * @example
+ * ```typescript
+ * const retention = new Retention(webId, endpoint, apiKey);
+ *
+ * // Track user activity
+ * await retention.trackActivity({
+ *   userId: 'user_123',
+ *   action: 'feature_used'
+ * });
+ *
+ * // Get cohort analysis
+ * const cohorts = await retention.getCohortAnalysis({
+ *   range: 'last90days',
+ *   granularity: 'week'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { RetentionCohort, UserLifecycleStage, LifecycleMetrics, DateRangeFilter, TimeGranularity, TimeSeriesData } from "../../types";
+/**
+ * Configuration for tracking user activity.
+ */
+export interface ActivityConfig {
+    /** User identifier */
+    userId: string;
+    /** Activity type/action */
+    action?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for cohort analysis.
+ */
+export interface CohortAnalysisConfig {
+    /** Date range for analysis */
+    filter?: DateRangeFilter;
+    /** Cohort granularity */
+    granularity?: TimeGranularity;
+    /** Segment by trait */
+    segmentBy?: string;
+    /** Number of periods to show */
+    periods?: number;
+}
+/**
+ * Activity tracking response.
+ */
+export interface ActivityResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        userId: string;
+        tracked: boolean;
+        daysSinceFirstSeen: number;
+        isReturning: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Cohort analysis data for charts.
+ */
+export interface CohortAnalysisData {
+    /** Cohort data */
+    cohorts: RetentionCohort[];
+    /** Retention matrix for heatmap */
+    matrix: Array<{
+        cohort: string;
+        periods: Array<{
+            period: number;
+            retained: number;
+            retentionRate: number;
+        }>;
+    }>;
+    /** Summary metrics */
+    summary: {
+        avgDay1Retention: number;
+        avgDay7Retention: number;
+        avgDay30Retention: number;
+        overallRetentionTrend: 'improving' | 'declining' | 'stable';
+    };
+}
+/**
+ * User stickiness data.
+ */
+export interface StickinessData {
+    /** DAU - Daily Active Users */
+    dau: number;
+    /** WAU - Weekly Active Users */
+    wau: number;
+    /** MAU - Monthly Active Users */
+    mau: number;
+    /** DAU/MAU ratio (stickiness) */
+    dauMauRatio: number;
+    /** DAU/WAU ratio */
+    dauWauRatio: number;
+    /** Stickiness trend over time */
+    trendData: TimeSeriesData;
+}
+/**
+ * Churn analysis data.
+ */
+export interface ChurnAnalysisData {
+    /** Current churn rate */
+    churnRate: number;
+    /** Users at risk of churning */
+    atRiskUsers: number;
+    /** Users who churned this period */
+    churnedUsers: number;
+    /** Churn by segment */
+    bySegment: Array<{
+        segment: string;
+        churnRate: number;
+        count: number;
+    }>;
+    /** Common churn factors */
+    churnFactors: Array<{
+        factor: string;
+        correlation: number;
+    }>;
+    /** Churn trend */
+    trendData: TimeSeriesData;
+}
+/**
+ * Retention - Track and analyze user retention.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides retention analysis capabilities including:
+ * - User activity tracking
+ * - Cohort-based retention analysis
+ * - Stickiness metrics (DAU/MAU)
+ * - Churn prediction and analysis
+ * - Lifecycle stage tracking
+ *
+ * @example
+ * ```typescript
+ * const retention = new Retention(webId, endpoint, apiKey);
+ *
+ * // Track daily user activity
+ * await retention.trackActivity({
+ *   userId: 'user_123',
+ *   action: 'daily_login'
+ * });
+ *
+ * // Analyze cohort retention
+ * const analysis = await retention.getCohortAnalysis({
+ *   granularity: 'week',
+ *   periods: 12
+ * });
+ *
+ * // Cohort heatmap data
+ * const heatmapData = analysis.matrix;
+ * ```
+ */
+export declare class Retention extends FTRPC {
+    /**
+     * Tracks user activity for retention calculation.
+     *
+     * @param config - Activity configuration
+     * @returns Promise resolving to activity response
+     *
+     * @example
+     * ```typescript
+     * // Track on app open
+     * await retention.trackActivity({
+     *   userId: 'user_123',
+     *   action: 'app_opened'
+     * });
+     *
+     * // Track specific feature usage
+     * await retention.trackActivity({
+     *   userId: 'user_123',
+     *   action: 'used_export',
+     *   properties: { format: 'pdf' }
+     * });
+     * ```
+     */
+    trackActivity(config: ActivityConfig): Promise<ActivityResponse>;
+    /**
+     * Tracks user lifecycle stage change.
+     *
+     * @param userId - User identifier
+     * @param stage - New lifecycle stage
+     * @param previousStage - Previous stage (optional)
+     * @returns Promise resolving to stage change response
+     */
+    trackLifecycleChange(userId: string, stage: UserLifecycleStage, previousStage?: UserLifecycleStage): Promise<ActivityResponse>;
+    /**
+     * Gets cohort-based retention analysis.
+     *
+     * @param config - Cohort analysis configuration
+     * @returns Promise resolving to cohort analysis data
+     *
+     * @example
+     * ```typescript
+     * const analysis = await retention.getCohortAnalysis({
+     *   filter: { range: 'last90days' },
+     *   granularity: 'week',
+     *   periods: 12
+     * });
+     *
+     * // Heatmap visualization
+     * const heatmap = analysis.matrix.map(cohort => ({
+     *   y: cohort.cohort,
+     *   data: cohort.periods.map(p => ({
+     *     x: `Period ${p.period}`,
+     *     value: p.retentionRate
+     *   }))
+     * }));
+     *
+     * // Retention curve (average across cohorts)
+     * const curve = [1, 7, 14, 30].map(day => ({
+     *   x: `Day ${day}`,
+     *   y: getAvgRetention(analysis.cohorts, day)
+     * }));
+     * ```
+     */
+    getCohortAnalysis(config?: CohortAnalysisConfig): Promise<CohortAnalysisData>;
+    /**
+     * Gets user stickiness metrics (DAU/MAU).
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to stickiness data
+     *
+     * @example
+     * ```typescript
+     * const stickiness = await retention.getStickiness({
+     *   range: 'last30days'
+     * });
+     *
+     * console.log(`DAU/MAU: ${(stickiness.dauMauRatio * 100).toFixed(1)}%`);
+     *
+     * // Trend chart
+     * const trendData = stickiness.trendData.data;
+     * ```
+     */
+    getStickiness(filter?: DateRangeFilter): Promise<StickinessData>;
+    /**
+     * Gets churn analysis and at-risk users.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to churn analysis data
+     *
+     * @example
+     * ```typescript
+     * const churn = await retention.getChurnAnalysis({
+     *   range: 'thisMonth'
+     * });
+     *
+     * // Alert on high churn segments
+     * churn.bySegment
+     *   .filter(s => s.churnRate > 0.1)
+     *   .forEach(s => console.warn(`High churn in ${s.segment}`));
+     * ```
+     */
+    getChurnAnalysis(filter?: DateRangeFilter): Promise<ChurnAnalysisData>;
+    /**
+     * Gets user lifecycle distribution.
+     *
+     * @returns Promise resolving to lifecycle metrics
+     */
+    getLifecycleMetrics(): Promise<LifecycleMetrics>;
+}
+export default Retention;

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

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Product Analytics - Session Tracking
+ * @module features/analytics/sessions
+ *
+ * @description
+ * Track user sessions with comprehensive context including device info,
+ * geographic location, traffic source, and engagement metrics.
+ *
+ * @useCases
+ * - Monitor active user sessions in real-time
+ * - Analyze session duration and depth
+ * - Track user journey across pages
+ * - Identify traffic sources and campaigns
+ * - Segment users by device and location
+ *
+ * @metrics
+ * - Total sessions
+ * - Unique visitors
+ * - Average session duration
+ * - Pages per session
+ * - Bounce rate
+ * - New vs returning visitors
+ *
+ * @chartData
+ * - Line chart: Sessions over time
+ * - Pie chart: Traffic source breakdown
+ * - Bar chart: Sessions by device type
+ * - Geo map: Sessions by country
+ *
+ * @example
+ * ```typescript
+ * const sessions = new Sessions(webId, endpoint, apiKey);
+ *
+ * // Start a new session
+ * const session = await sessions.start({
+ *   userId: 'user_123',
+ *   device: { type: 'desktop', browser: 'Chrome' },
+ *   source: 'google',
+ *   medium: 'organic'
+ * });
+ *
+ * // End session
+ * await sessions.end(session.sessionId);
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { DeviceInfo, GeoLocation, UTMParams, TimeSeriesData, DateRangeFilter, PaginationParams, UserIdentity } from "../../types";
+/**
+ * Configuration for starting a new session.
+ */
+export interface SessionStartConfig {
+    /** User identity */
+    user?: UserIdentity;
+    /** Device information */
+    device?: DeviceInfo;
+    /** Geographic location */
+    location?: GeoLocation;
+    /** Traffic source */
+    source?: string;
+    /** Traffic medium */
+    medium?: string;
+    /** Campaign name */
+    campaign?: string;
+    /** UTM parameters */
+    utm?: UTMParams;
+    /** Landing page URL */
+    landingPage?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Session response from API.
+ */
+export interface SessionResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        sessionId: string;
+        started: boolean;
+        isNewVisitor: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Session end response.
+ */
+export interface SessionEndResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        sessionId: string;
+        duration: number;
+        pageViews: number;
+        eventCount: number;
+    };
+    timestamp: string;
+}
+/**
+ * Session analytics data for charts.
+ */
+export interface SessionAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalSessions: number;
+        uniqueVisitors: number;
+        newVisitors: number;
+        returningVisitors: number;
+        avgSessionDuration: number;
+        avgPagesPerSession: number;
+        bounceRate: number;
+    };
+    /** Sessions time series */
+    timeSeries: TimeSeriesData;
+    /** Sessions by source */
+    bySource: Array<{
+        source: string;
+        sessions: number;
+        percentage: number;
+    }>;
+    /** Sessions by device */
+    byDevice: Array<{
+        device: string;
+        sessions: number;
+        percentage: number;
+    }>;
+    /** Sessions by country */
+    byCountry: Array<{
+        country: string;
+        countryCode: string;
+        sessions: number;
+    }>;
+}
+/**
+ * Real-time session data.
+ */
+export interface RealTimeSessionData {
+    /** Currently active sessions */
+    activeSessions: number;
+    /** Active users in last 5 minutes */
+    activeUsers5min: number;
+    /** Active users in last 30 minutes */
+    activeUsers30min: number;
+    /** Sessions by page (real-time) */
+    sessionsByPage: Array<{
+        path: string;
+        count: number;
+    }>;
+    /** Sessions by country (real-time) */
+    sessionsByCountry: Array<{
+        country: string;
+        count: number;
+    }>;
+}
+/**
+ * Sessions - Track and analyze user sessions.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides comprehensive session tracking including:
+ * - Session lifecycle (start, update, end)
+ * - Device and location tracking
+ * - Traffic source attribution
+ * - Real-time session monitoring
+ * - Session replay triggers
+ *
+ * @example
+ * ```typescript
+ * const sessions = new Sessions(webId, endpoint, apiKey);
+ *
+ * // Start session on page load
+ * const session = await sessions.start({
+ *   user: { userId: 'user_123' },
+ *   device: { type: 'mobile', os: 'iOS' },
+ *   source: 'email',
+ *   campaign: 'summer_sale'
+ * });
+ *
+ * // Get real-time data
+ * const realTime = await sessions.getRealTime();
+ * console.log(`${realTime.activeSessions} users online`);
+ * ```
+ */
+export declare class Sessions extends FTRPC {
+    /**
+     * Starts a new user session.
+     *
+     * @param config - Session configuration
+     * @returns Promise resolving to session response with sessionId
+     *
+     * @example
+     * ```typescript
+     * const session = await sessions.start({
+     *   user: { userId: 'user_123' },
+     *   source: 'google',
+     *   medium: 'cpc',
+     *   campaign: 'brand_terms'
+     * });
+     * localStorage.setItem('sessionId', session.response.sessionId);
+     * ```
+     */
+    start(config?: SessionStartConfig): Promise<SessionResponse>;
+    /**
+     * Updates an existing session with new data.
+     *
+     * @param sessionId - Session identifier
+     * @param properties - Properties to update
+     * @returns Promise resolving to update response
+     */
+    update(sessionId: string, properties: Record<string, unknown>): Promise<SessionResponse>;
+    /**
+     * Ends a user session.
+     *
+     * @param sessionId - Session identifier to end
+     * @returns Promise resolving to session end response with metrics
+     *
+     * @example
+     * ```typescript
+     * window.addEventListener('beforeunload', async () => {
+     *   const sessionId = localStorage.getItem('sessionId');
+     *   if (sessionId) {
+     *     await sessions.end(sessionId);
+     *   }
+     * });
+     * ```
+     */
+    end(sessionId: string): Promise<SessionEndResponse>;
+    /**
+     * Tracks a heartbeat to keep session alive.
+     *
+     * @param sessionId - Session identifier
+     * @returns Promise resolving to heartbeat response
+     */
+    heartbeat(sessionId: string): Promise<SessionResponse>;
+    /**
+     * Retrieves session analytics data for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @param pagination - Pagination options
+     * @returns Promise resolving to session analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await sessions.getAnalytics({
+     *   range: 'last7days'
+     * });
+     *
+     * // For pie chart - traffic sources
+     * const sourceData = analytics.bySource.map(s => ({
+     *   name: s.source,
+     *   value: s.sessions
+     * }));
+     *
+     * // For line chart - sessions over time
+     * const trendData = analytics.timeSeries.data;
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter, pagination?: PaginationParams): Promise<SessionAnalyticsData>;
+    /**
+     * Gets real-time session data for live dashboards.
+     *
+     * @returns Promise resolving to real-time session data
+     *
+     * @example
+     * ```typescript
+     * // Poll for real-time updates
+     * setInterval(async () => {
+     *   const realTime = await sessions.getRealTime();
+     *   updateDashboard(realTime.activeSessions);
+     * }, 10000);
+     * ```
+     */
+    getRealTime(): Promise<RealTimeSessionData>;
+}
+export default Sessions;