flowgrid-sdk 1.0.0

package/dist/lib/features/enterprise/engagement.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Enterprise - Engagement Analytics
+ * @module features/enterprise/engagement
+ *
+ * @description
+ * Track deep user engagement beyond activation including
+ * feature dwell time, session depth, and content consumption.
+ *
+ * @useCases
+ * - Measure feature dwell time
+ * - Track session depth and engagement
+ * - Monitor content consumption patterns
+ * - Distinguish active vs passive users
+ * - Correlate engagement with retention
+ *
+ * @metrics
+ * - Average engagement time
+ * - Feature dwell time
+ * - Session depth score
+ * - Content consumption rate
+ * - Active user ratio
+ *
+ * @chartData
+ * - Line chart: Engagement over time
+ * - Bar chart: Engagement by feature
+ * - Heatmap: Engagement by time of day
+ * - Distribution: User engagement scores
+ *
+ * @example
+ * ```typescript
+ * const engagement = new Engagement(webId, endpoint, apiKey);
+ *
+ * // Track feature dwell time
+ * await engagement.trackDwellTime({
+ *   featureId: 'dashboard',
+ *   userId: 'user_123',
+ *   dwellTimeMs: 45000
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Configuration for tracking feature dwell time.
+ */
+export interface DwellTimeConfig {
+    /** Feature identifier */
+    featureId: string;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Time spent on feature (ms) */
+    dwellTimeMs: number;
+    /** Whether user was actively interacting */
+    wasActive?: boolean;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for tracking session depth.
+ */
+export interface SessionDepthConfig {
+    /** Session ID */
+    sessionId: string;
+    /** User ID */
+    userId?: string;
+    /** Number of pages/screens visited */
+    pagesVisited: number;
+    /** Number of features used */
+    featuresUsed: number;
+    /** Number of actions taken */
+    actionsTaken: number;
+    /** Total session duration (ms) */
+    durationMs: number;
+}
+/**
+ * Configuration for tracking content consumption.
+ */
+export interface ContentConsumptionConfig {
+    /** Content identifier */
+    contentId: string;
+    /** Content type */
+    contentType: 'article' | 'video' | 'audio' | 'document' | 'course' | 'other';
+    /** User ID */
+    userId?: string;
+    /** Percentage consumed (0-100) */
+    percentageConsumed: number;
+    /** Time spent consuming (ms) */
+    timeSpentMs: number;
+    /** Whether content was completed */
+    completed?: boolean;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * User activity classification.
+ */
+export interface UserActivityConfig {
+    /** User ID */
+    userId: string;
+    /** Activity type */
+    activityType: 'active' | 'passive' | 'idle';
+    /** Duration in this state (ms) */
+    durationMs: number;
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Engagement score configuration.
+ */
+export interface EngagementScoreConfig {
+    /** User ID */
+    userId: string;
+    /** Time period for score calculation */
+    period?: 'day' | 'week' | 'month';
+}
+/**
+ * Engagement analytics filter.
+ */
+export interface EngagementAnalyticsFilter extends DateRangeFilter {
+    /** Filter by feature */
+    featureId?: string;
+    /** Filter by user segment */
+    segment?: string;
+    /** Minimum engagement score */
+    minScore?: number;
+}
+/**
+ * Engagement response from API.
+ */
+export interface EngagementResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: boolean;
+        engagementId: string;
+        timestamp: string;
+    };
+}
+/**
+ * Engagement score result.
+ */
+export interface EngagementScore {
+    userId: string;
+    score: number;
+    percentile: number;
+    breakdown: {
+        dwellTime: number;
+        sessionDepth: number;
+        contentConsumption: number;
+        activityLevel: number;
+    };
+    trend: 'increasing' | 'stable' | 'decreasing';
+    period: string;
+}
+/**
+ * Engagement analytics result.
+ */
+export interface EngagementAnalytics {
+    averageEngagementScore: number;
+    averageDwellTimeMs: number;
+    averageSessionDepth: number;
+    activeUserRatio: number;
+    contentCompletionRate: number;
+    topEngagedFeatures: Array<{
+        featureId: string;
+        averageDwellTime: number;
+        userCount: number;
+    }>;
+    engagementTrend: TimeSeriesData;
+}
+/**
+ * Calculate engagement score from multiple factors.
+ */
+export declare function calculateEngagementScore(dwellTime: number, sessionDepth: number, activityRatio: number, contentCompletion: number): number;
+/**
+ * Classify user engagement level.
+ */
+export declare function classifyEngagementLevel(score: number): 'low' | 'medium' | 'high' | 'power';
+/**
+ * Calculate session depth score.
+ */
+export declare function calculateSessionDepthScore(pagesVisited: number, featuresUsed: number, actionsTaken: number): number;
+/**
+ * Engagement analytics tracking class.
+ */
+export declare class Engagement extends EnterpriseFTRPC {
+    /**
+     * Track feature dwell time.
+     */
+    trackDwellTime(config: DwellTimeConfig): Promise<EngagementResponse>;
+    /**
+     * Track session depth.
+     */
+    trackSessionDepth(config: SessionDepthConfig): Promise<EngagementResponse>;
+    /**
+     * Track content consumption.
+     */
+    trackContentConsumption(config: ContentConsumptionConfig): Promise<EngagementResponse>;
+    /**
+     * Track user activity state.
+     */
+    trackUserActivity(config: UserActivityConfig): Promise<EngagementResponse>;
+    /**
+     * Get engagement score for a user.
+     */
+    getEngagementScore(config: EngagementScoreConfig): Promise<EngagementScore>;
+    /**
+     * Get engagement analytics.
+     */
+    getAnalytics(filter?: EngagementAnalyticsFilter): Promise<EngagementAnalytics>;
+    /**
+     * Get engagement trend over time.
+     */
+    getEngagementTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get top engaged users.
+     */
+    getTopEngagedUsers(filter?: DateRangeFilter, limit?: number): Promise<Array<{
+        userId: string;
+        score: number;
+        level: string;
+    }>>;
+    /**
+     * Get engagement by feature.
+     */
+    getEngagementByFeature(filter?: DateRangeFilter): Promise<Array<{
+        featureId: string;
+        avgDwellTime: number;
+        uniqueUsers: number;
+    }>>;
+}

package/dist/lib/features/enterprise/forecasting.d.ts

@@ -0,0 +1,351 @@
+/**
+ * @fileoverview Enterprise - Product Usage Forecasting
+ * @module features/enterprise/forecasting
+ *
+ * @description
+ * Predict usage, adoption, and revenue trends using historical data
+ * and machine learning models.
+ *
+ * @useCases
+ * - Project active user growth
+ * - Forecast feature adoption
+ * - Predict churn and revenue
+ * - Capacity planning
+ * - Trend analysis
+ *
+ * @metrics
+ * - Predicted DAU/MAU
+ * - Feature adoption forecast
+ * - Revenue projection
+ * - Churn prediction
+ * - Forecast accuracy
+ *
+ * @chartData
+ * - Line chart: Forecast with confidence
+ * - Area chart: Prediction range
+ * - Comparison: Predicted vs actual
+ * - Table: Forecast metrics
+ *
+ * @example
+ * ```typescript
+ * const forecasting = new Forecasting(webId, endpoint, apiKey);
+ *
+ * // Get user growth forecast
+ * const forecast = await forecasting.forecastActiveUsers({
+ *   metric: 'dau',
+ *   periods: 30,
+ *   granularity: 'day'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeGranularity, MoneyValue, CurrencyCode } from "../../types";
+/**
+ * Forecast model types.
+ */
+export type ForecastModel = 'linear' | 'exponential' | 'arima' | 'prophet' | 'ensemble';
+/**
+ * Metric types for forecasting.
+ */
+export type ForecastMetric = 'dau' | 'wau' | 'mau' | 'signups' | 'revenue' | 'mrr' | 'churn_rate' | 'feature_usage' | 'sessions' | 'events' | 'custom';
+/**
+ * Base forecast configuration.
+ */
+export interface ForecastConfig {
+    /** Metric to forecast */
+    metric: ForecastMetric;
+    /** Number of periods to forecast */
+    periods: number;
+    /** Time granularity */
+    granularity: TimeGranularity;
+    /** Historical data range to use */
+    historicalRange?: DateRangeFilter;
+    /** Forecast model to use */
+    model?: ForecastModel;
+    /** Include confidence intervals */
+    includeConfidence?: boolean;
+    /** Confidence level (0-1, default 0.95) */
+    confidenceLevel?: number;
+    /** Custom metric name (if metric is 'custom') */
+    customMetricName?: string;
+}
+/**
+ * Forecast data point.
+ */
+export interface ForecastDataPoint {
+    /** Period/date */
+    period: string;
+    /** Predicted value */
+    predicted: number;
+    /** Lower bound (if confidence included) */
+    lower?: number;
+    /** Upper bound (if confidence included) */
+    upper?: number;
+    /** Actual value (if historical/backtested) */
+    actual?: number;
+}
+/**
+ * Forecast result.
+ */
+export interface ForecastResult {
+    /** Metric being forecasted */
+    metric: ForecastMetric;
+    /** Model used */
+    model: ForecastModel;
+    /** Granularity */
+    granularity: TimeGranularity;
+    /** Forecast data points */
+    forecast: ForecastDataPoint[];
+    /** Summary statistics */
+    summary: {
+        startValue: number;
+        endValue: number;
+        totalChange: number;
+        changePercent: number;
+        trend: 'growing' | 'stable' | 'declining';
+        avgGrowthRate: number;
+    };
+    /** Model accuracy (based on backtesting) */
+    accuracy: {
+        mape: number;
+        rmse: number;
+        r2: number;
+    };
+    /** Generated at */
+    generatedAt: string;
+}
+/**
+ * Revenue forecast configuration.
+ */
+export interface RevenueForecastConfig extends Omit<ForecastConfig, 'metric'> {
+    /** Currency */
+    currency?: CurrencyCode;
+    /** Include MRR components */
+    includeMRRComponents?: boolean;
+}
+/**
+ * Revenue forecast result.
+ */
+export interface RevenueForecastResult extends ForecastResult {
+    /** Currency */
+    currency: CurrencyCode;
+    /** MRR components (if included) */
+    mrrComponents?: {
+        newBusiness: ForecastDataPoint[];
+        expansion: ForecastDataPoint[];
+        contraction: ForecastDataPoint[];
+        churn: ForecastDataPoint[];
+    };
+}
+/**
+ * Feature adoption forecast configuration.
+ */
+export interface FeatureAdoptionForecastConfig extends Omit<ForecastConfig, 'metric'> {
+    /** Feature ID */
+    featureId: string;
+    /** Adoption metric */
+    adoptionMetric?: 'users' | 'usage_count' | 'adoption_rate';
+}
+/**
+ * Churn forecast configuration.
+ */
+export interface ChurnForecastConfig extends Omit<ForecastConfig, 'metric'> {
+    /** User segment */
+    segment?: string;
+    /** Include user-level predictions */
+    includeUserPredictions?: boolean;
+    /** Top N at-risk users to include */
+    topAtRiskUsers?: number;
+}
+/**
+ * Churn forecast result.
+ */
+export interface ChurnForecastResult extends ForecastResult {
+    /** Predicted churned user count */
+    predictedChurnedUsers: number;
+    /** Predicted revenue at risk */
+    revenueAtRisk?: MoneyValue;
+    /** Top at-risk users (if requested) */
+    atRiskUsers?: Array<{
+        userId: string;
+        churnProbability: number;
+        predictedChurnDate: string;
+        estimatedValue: MoneyValue;
+    }>;
+}
+/**
+ * Capacity planning configuration.
+ */
+export interface CapacityPlanningConfig {
+    /** Metrics to include */
+    metrics: Array<'users' | 'sessions' | 'events' | 'api_calls' | 'storage'>;
+    /** Periods to forecast */
+    periods: number;
+    /** Granularity */
+    granularity: 'week' | 'month' | 'quarter';
+    /** Current capacity limits */
+    currentLimits?: Record<string, number>;
+}
+/**
+ * Capacity planning result.
+ */
+export interface CapacityPlanningResult {
+    /** Forecasts by metric */
+    forecasts: Record<string, ForecastResult>;
+    /** Capacity alerts */
+    alerts: Array<{
+        metric: string;
+        currentUsage: number;
+        limit: number;
+        predictedExceedDate?: string;
+        recommendation: string;
+    }>;
+    /** Overall growth rate */
+    overallGrowthRate: number;
+}
+/**
+ * Scenario configuration.
+ */
+export interface ScenarioConfig {
+    /** Base forecast configuration */
+    baseConfig: ForecastConfig;
+    /** Scenario adjustments */
+    scenarios: Array<{
+        name: string;
+        adjustments: {
+            growthMultiplier?: number;
+            seasonalAdjustment?: number;
+            oneTimeImpact?: {
+                period: string;
+                value: number;
+            };
+        };
+    }>;
+}
+/**
+ * Scenario comparison result.
+ */
+export interface ScenarioComparison {
+    /** Base forecast */
+    baseline: ForecastResult;
+    /** Scenario forecasts */
+    scenarios: Array<{
+        name: string;
+        forecast: ForecastResult;
+        differenceFromBaseline: number;
+    }>;
+}
+/**
+ * Calculate MAPE (Mean Absolute Percentage Error).
+ */
+export declare function calculateMAPE(actual: number[], predicted: number[]): number;
+/**
+ * Calculate RMSE (Root Mean Square Error).
+ */
+export declare function calculateRMSE(actual: number[], predicted: number[]): number;
+/**
+ * Calculate R-squared.
+ */
+export declare function calculateR2(actual: number[], predicted: number[]): number;
+/**
+ * Classify trend direction.
+ */
+export declare function classifyTrend(startValue: number, endValue: number, threshold?: number): 'growing' | 'stable' | 'declining';
+/**
+ * Calculate average growth rate.
+ */
+export declare function calculateAvgGrowthRate(values: number[]): number;
+/**
+ * Apply confidence interval.
+ */
+export declare function applyConfidenceInterval(predicted: number, stdError: number, confidenceLevel?: number): {
+    lower: number;
+    upper: number;
+};
+/**
+ * Product usage forecasting class.
+ */
+export declare class Forecasting extends EnterpriseFTRPC {
+    /**
+     * Forecast active users.
+     */
+    forecastActiveUsers(config: ForecastConfig): Promise<ForecastResult>;
+    /**
+     * Forecast revenue.
+     */
+    forecastRevenue(config: RevenueForecastConfig): Promise<RevenueForecastResult>;
+    /**
+     * Forecast MRR.
+     */
+    forecastMRR(config: RevenueForecastConfig): Promise<RevenueForecastResult>;
+    /**
+     * Forecast feature adoption.
+     */
+    forecastFeatureAdoption(config: FeatureAdoptionForecastConfig): Promise<ForecastResult>;
+    /**
+     * Forecast churn.
+     */
+    forecastChurn(config: ChurnForecastConfig): Promise<ChurnForecastResult>;
+    /**
+     * Forecast signups.
+     */
+    forecastSignups(config: ForecastConfig): Promise<ForecastResult>;
+    /**
+     * Get capacity planning forecast.
+     */
+    getCapacityPlanning(config: CapacityPlanningConfig): Promise<CapacityPlanningResult>;
+    /**
+     * Compare forecast scenarios.
+     */
+    compareScenarios(config: ScenarioConfig): Promise<ScenarioComparison>;
+    /**
+     * Forecast custom metric.
+     */
+    forecastCustomMetric(metricName: string, config: Omit<ForecastConfig, 'metric' | 'customMetricName'>): Promise<ForecastResult>;
+    /**
+     * Get forecast accuracy report.
+     */
+    getForecastAccuracy(metric: ForecastMetric, lookbackPeriods: number): Promise<{
+        metric: ForecastMetric;
+        periods: Array<{
+            period: string;
+            predicted: number;
+            actual: number;
+            error: number;
+            errorPercent: number;
+        }>;
+        overallAccuracy: {
+            mape: number;
+            rmse: number;
+            r2: number;
+        };
+    }>;
+    /**
+     * Get growth projections.
+     */
+    getGrowthProjections(periods: number, granularity: TimeGranularity): Promise<{
+        users: ForecastResult;
+        revenue: ForecastResult;
+        engagement: ForecastResult;
+        summary: {
+            projectedUsersEnd: number;
+            projectedRevenueEnd: MoneyValue;
+            avgMonthlyGrowth: number;
+        };
+    }>;
+    /**
+     * Get what-if analysis.
+     */
+    getWhatIfAnalysis(baseMetric: ForecastMetric, adjustments: Array<{
+        factor: string;
+        change: number;
+    }>, periods: number): Promise<{
+        baseline: ForecastResult;
+        adjusted: ForecastResult;
+        impact: {
+            absoluteDiff: number;
+            percentDiff: number;
+            sensitivityScore: number;
+        };
+    }>;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Enterprise Features Module
+ * @module features/enterprise
+ *
+ * @description
+ * Advanced analytics features for enterprise-tier users.
+ * Includes engagement, cohorts, churn, monetization, funnels,
+ * support, acquisition, path analysis, alerts, security, and forecasting.
+ */
+export { Engagement, type DwellTimeConfig, type SessionDepthConfig, type ContentConsumptionConfig, type UserActivityConfig, type EngagementScoreConfig, type EngagementAnalyticsFilter, type EngagementResponse, type EngagementScore, type EngagementAnalytics, calculateEngagementScore, classifyEngagementLevel, calculateSessionDepthScore } from './engagement';
+export { Cohorts, type CohortOperator, type CohortRule, type CohortType, type CohortDefinition, type SegmentDefinition, type CohortAssignment, type CohortComparisonConfig, type CohortAnalyticsFilter, type CohortResponse, type CohortMember, type CohortAnalytics, type CohortComparison, evaluateCohortRules, generateCohortId } from './cohorts';
+export { ChurnAnalytics, type ChurnRiskFactors, type ChurnRiskScore, type UsageDecayConfig, type UsageDecay, type NPSConfig, type ChurnEventConfig, type PreventionActionConfig, type AtRiskUsersFilter, type ChurnAnalyticsResult, calculateChurnRiskScore, classifyRiskLevel, generateRecommendations } from './churn';
+export { Monetization, type RevenueType, type RevenueTrackConfig, type ARPUConfig, type ARPUResult, type CohortRevenueConfig, type CohortRevenueResult, type PlanAnalysisConfig, type PlanAnalysis, type RevenueBreakdownConfig, type RevenueBreakdown, type NRRConfig, type NRRResult, type RevenueForecastConfig, type RevenueForecast, type MonetizationAnalytics, calculateARPU, calculateNRR, calculateGRR, monthlyToAnnual, calculateLTV } from './monetization';
+export { MultiPathFunnels, type FunnelPath, type MultiPathFunnelDefinition, type MicroConversionDefinition, type MultiPathStepConfig, type MicroConversionConfig, type FunnelAnalysisConfig, type PathAnalysis, type MicroConversionAnalysis, type MultiPathFunnelAnalysis, type SegmentDropOffAnalysis, type UserJourneyConfig, type UserJourney, calculateConversionRate, calculateDropOffRate, findBestPath, calculateMicroConversionScore, generatePathId } from './multi-path-funnels';
+export { SupportAnalytics, type TicketPriority, type TicketStatus, type SupportChannel, type TicketConfig, type TicketUpdateConfig, type CSATConfig, type FeatureComplaintConfig, type SupportAnalyticsFilter, type TicketAnalytics, type SupportImpactAnalysis, type FeatureComplaintSummary, type AgentPerformance, calculateFCRRate, calculateAvgResponseTime, classifyCSAT, formatDuration } from './support';
+export { AcquisitionAnalytics, type AcquisitionSource, type LifecycleStage, type AcquisitionConfig, type CampaignDefinition, type CampaignSpendConfig, type LifecycleTransitionConfig, type CACConfig, type CACResult, type TrialFunnelConfig, type TrialFunnelResult, type CampaignPerformance, type AttributionModel, type AttributionAnalysisConfig, type AttributionResult, type AcquisitionAnalytics as AcquisitionAnalyticsType, calculateCAC, calculateROAS, calculateLTVCACRatio, parseUTMParams, classifySource } from './acquisition';
+export { PathAnalytics, type TransitionConfig, type FeatureSequenceConfig, type PathDefinition, type PathAnalysisConfig, type PathResult, type DeadEndScreen, type TransitionMatrix, type UserJourneyConfig as PathUserJourneyConfig, type UserJourney as PathUserJourney, type FrictionPoint, type PathComparison, pathToString, stringToPath, calculateExitRate, isDeadEnd, calculatePathSimilarity, findCommonSubPaths } from './paths';
+export { AlertsAnalytics, type AlertCondition, type AlertSeverity, type AlertStatus, type NotificationChannel, type AlertRuleDefinition, type AlertInstance, type AnomalyDetectionConfig, type Anomaly, type NotificationConfig, type AlertAnalyticsFilter, type AlertAnalytics, calculateStdDev, calculateZScore, isAnomaly, calculateAnomalyScore, classifySeverity, checkAlertCondition } from './alerts';
+export { SecurityAnalytics, type SecurityEventType, type ComplianceEventType, type LoginAttemptConfig, type RoleChangeConfig, type PermissionChangeConfig, type DataAccessConfig, type ComplianceEventConfig, type AuditLogEntry, type SecurityAnalyticsFilter, type SecurityRiskAssessment, type SecurityAnalytics as SecurityAnalyticsType, type ComplianceReport, classifyRiskLevel as classifySecurityRiskLevel, calculateFailedLoginRate, isSuspiciousLoginPattern, determineEventSeverity } from './security';
+export { Forecasting, type ForecastModel, type ForecastMetric, type ForecastConfig, type ForecastDataPoint, type ForecastResult, type RevenueForecastConfig as ForecastingRevenueForecastConfig, type RevenueForecastResult, type FeatureAdoptionForecastConfig, type ChurnForecastConfig, type ChurnForecastResult, type CapacityPlanningConfig, type CapacityPlanningResult, type ScenarioConfig, type ScenarioComparison, calculateMAPE, calculateRMSE, calculateR2, classifyTrend, calculateAvgGrowthRate, applyConfidenceInterval } from './forecasting';