flowgrid-sdk 1.0.0

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

@@ -0,0 +1,356 @@
+/**
+ * @fileoverview Enterprise - Revenue & Monetization Analytics
+ * @module features/enterprise/monetization
+ *
+ * @description
+ * Track detailed revenue and monetization KPIs including ARPU,
+ * cohort-based revenue, and pricing plan impact analysis.
+ *
+ * @useCases
+ * - Calculate ARPU/ARPA per segment
+ * - Track cohort-based revenue
+ * - Analyze pricing plan impact
+ * - Revenue forecasting
+ * - Expansion revenue tracking
+ *
+ * @metrics
+ * - ARPU (Average Revenue Per User)
+ * - ARPA (Average Revenue Per Account)
+ * - Revenue by cohort
+ * - Revenue by plan
+ * - Expansion revenue
+ * - Net Revenue Retention
+ *
+ * @chartData
+ * - Line chart: Revenue over time
+ * - Bar chart: Revenue by segment
+ * - Waterfall: Revenue movement
+ * - Cohort: Revenue retention
+ *
+ * @example
+ * ```typescript
+ * const monetization = new Monetization(webId, endpoint, apiKey);
+ *
+ * // Get ARPU by segment
+ * const arpu = await monetization.getARPU({ segment: 'enterprise' });
+ *
+ * // Track revenue event
+ * await monetization.trackRevenue({
+ *   userId: 'user_123',
+ *   amount: 99.00,
+ *   currency: 'USD',
+ *   type: 'subscription'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity, MoneyValue, CurrencyCode } from "../../types";
+/**
+ * Revenue event types.
+ */
+export type RevenueType = 'subscription' | 'one_time' | 'expansion' | 'renewal' | 'downgrade' | 'refund' | 'credit';
+/**
+ * Revenue tracking configuration.
+ */
+export interface RevenueTrackConfig {
+    /** User ID */
+    userId: string;
+    /** Account/company ID (for B2B) */
+    accountId?: string;
+    /** Revenue amount */
+    amount: number;
+    /** Currency code */
+    currency: CurrencyCode;
+    /** Revenue type */
+    type: RevenueType;
+    /** Associated plan/product */
+    planId?: string;
+    /** Transaction ID */
+    transactionId?: string;
+    /** Billing period */
+    billingPeriod?: 'monthly' | 'quarterly' | 'annual';
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * ARPU calculation configuration.
+ */
+export interface ARPUConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Segment by attribute */
+    segment?: string;
+    /** User type filter */
+    userType?: 'all' | 'paid' | 'free';
+    /** Calculation period */
+    period?: 'daily' | 'monthly' | 'annual';
+}
+/**
+ * ARPU result.
+ */
+export interface ARPUResult {
+    /** ARPU value */
+    arpu: MoneyValue;
+    /** Number of users in calculation */
+    userCount: number;
+    /** Total revenue in period */
+    totalRevenue: MoneyValue;
+    /** Period of calculation */
+    period: string;
+    /** Comparison with previous period */
+    change?: {
+        absolute: MoneyValue;
+        percentage: number;
+    };
+}
+/**
+ * Cohort revenue configuration.
+ */
+export interface CohortRevenueConfig {
+    /** Cohort identifier or definition */
+    cohortId?: string;
+    /** Cohort start date */
+    cohortDate?: string;
+    /** Periods to track */
+    periods: number;
+    /** Granularity */
+    granularity: 'week' | 'month' | 'quarter';
+}
+/**
+ * Cohort revenue result.
+ */
+export interface CohortRevenueResult {
+    cohortId: string;
+    cohortDate: string;
+    cohortSize: number;
+    periods: Array<{
+        period: number;
+        revenue: MoneyValue;
+        arpu: MoneyValue;
+        retainedUsers: number;
+        retentionRate: number;
+        cumulativeRevenue: MoneyValue;
+    }>;
+    ltvProjection: MoneyValue;
+}
+/**
+ * Plan analysis configuration.
+ */
+export interface PlanAnalysisConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Specific plans to analyze */
+    planIds?: string[];
+}
+/**
+ * Plan analysis result.
+ */
+export interface PlanAnalysis {
+    planId: string;
+    planName: string;
+    activeUsers: number;
+    revenue: MoneyValue;
+    arpu: MoneyValue;
+    churnRate: number;
+    upgrades: number;
+    downgrades: number;
+    growthRate: number;
+}
+/**
+ * Revenue breakdown configuration.
+ */
+export interface RevenueBreakdownConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Breakdown dimension */
+    dimension: 'type' | 'plan' | 'segment' | 'country' | 'source';
+}
+/**
+ * Revenue breakdown result.
+ */
+export interface RevenueBreakdown {
+    dimension: string;
+    breakdown: Array<{
+        value: string;
+        revenue: MoneyValue;
+        percentage: number;
+        userCount: number;
+    }>;
+    total: MoneyValue;
+}
+/**
+ * Net revenue retention configuration.
+ */
+export interface NRRConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Calculation period */
+    period?: 'monthly' | 'quarterly' | 'annual';
+}
+/**
+ * Net revenue retention result.
+ */
+export interface NRRResult {
+    /** Net Revenue Retention rate */
+    nrr: number;
+    /** Gross Revenue Retention */
+    grr: number;
+    /** Starting MRR */
+    startingMRR: MoneyValue;
+    /** Expansion revenue */
+    expansion: MoneyValue;
+    /** Contraction revenue */
+    contraction: MoneyValue;
+    /** Churned revenue */
+    churned: MoneyValue;
+    /** Ending MRR */
+    endingMRR: MoneyValue;
+    /** Period */
+    period: string;
+}
+/**
+ * Revenue forecast configuration.
+ */
+export interface RevenueForecastConfig {
+    /** Periods to forecast */
+    periods: number;
+    /** Granularity */
+    granularity: 'month' | 'quarter';
+    /** Include confidence intervals */
+    includeConfidence?: boolean;
+}
+/**
+ * Revenue forecast result.
+ */
+export interface RevenueForecast {
+    forecasts: Array<{
+        period: string;
+        predicted: MoneyValue;
+        confidence?: {
+            low: MoneyValue;
+            high: MoneyValue;
+        };
+    }>;
+    model: string;
+    accuracy: number;
+}
+/**
+ * Monetization analytics result.
+ */
+export interface MonetizationAnalytics {
+    totalRevenue: MoneyValue;
+    mrr: MoneyValue;
+    arr: MoneyValue;
+    arpu: MoneyValue;
+    nrr: number;
+    grr: number;
+    expansionRate: number;
+    revenueGrowthRate: number;
+    paidUserCount: number;
+    conversionRate: number;
+    revenueByType: RevenueBreakdown;
+    trend: TimeSeriesData;
+}
+/**
+ * Calculate ARPU from total revenue and user count.
+ */
+export declare function calculateARPU(totalRevenue: number, userCount: number, currency: CurrencyCode): MoneyValue;
+/**
+ * Calculate Net Revenue Retention.
+ */
+export declare function calculateNRR(startingMRR: number, expansion: number, contraction: number, churned: number): number;
+/**
+ * Calculate Gross Revenue Retention.
+ */
+export declare function calculateGRR(startingMRR: number, contraction: number, churned: number): number;
+/**
+ * Convert monthly to annual revenue.
+ */
+export declare function monthlyToAnnual(mrr: MoneyValue): MoneyValue;
+/**
+ * Calculate LTV from ARPU and churn rate.
+ */
+export declare function calculateLTV(arpu: number, monthlyChurnRate: number, currency: CurrencyCode): MoneyValue;
+/**
+ * Revenue and monetization analytics class.
+ */
+export declare class Monetization extends EnterpriseFTRPC {
+    /**
+     * Track revenue event.
+     */
+    trackRevenue(config: RevenueTrackConfig): Promise<{
+        tracked: boolean;
+        revenueId: string;
+    }>;
+    /**
+     * Track expansion revenue.
+     */
+    trackExpansion(userId: string, fromPlan: string, toPlan: string, additionalRevenue: MoneyValue): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track contraction/downgrade.
+     */
+    trackContraction(userId: string, fromPlan: string, toPlan: string, reducedRevenue: MoneyValue): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Get ARPU.
+     */
+    getARPU(config?: ARPUConfig): Promise<ARPUResult>;
+    /**
+     * Get ARPU by segment.
+     */
+    getARPUBySegment(segmentAttribute: string, filter?: DateRangeFilter): Promise<Array<{
+        segment: string;
+        arpu: MoneyValue;
+        userCount: number;
+    }>>;
+    /**
+     * Get cohort revenue analysis.
+     */
+    getCohortRevenue(config: CohortRevenueConfig): Promise<CohortRevenueResult>;
+    /**
+     * Get plan analysis.
+     */
+    getPlanAnalysis(config?: PlanAnalysisConfig): Promise<PlanAnalysis[]>;
+    /**
+     * Get revenue breakdown.
+     */
+    getRevenueBreakdown(config: RevenueBreakdownConfig): Promise<RevenueBreakdown>;
+    /**
+     * Get Net Revenue Retention.
+     */
+    getNRR(config?: NRRConfig): Promise<NRRResult>;
+    /**
+     * Get MRR.
+     */
+    getMRR(filter?: DateRangeFilter): Promise<MoneyValue>;
+    /**
+     * Get ARR.
+     */
+    getARR(filter?: DateRangeFilter): Promise<MoneyValue>;
+    /**
+     * Get revenue forecast.
+     */
+    getRevenueForecast(config: RevenueForecastConfig): Promise<RevenueForecast>;
+    /**
+     * Get monetization analytics.
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<MonetizationAnalytics>;
+    /**
+     * Get revenue trend.
+     */
+    getRevenueTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get MRR movement (waterfall).
+     */
+    getMRRMovement(filter?: DateRangeFilter): Promise<{
+        starting: MoneyValue;
+        newBusiness: MoneyValue;
+        expansion: MoneyValue;
+        contraction: MoneyValue;
+        churn: MoneyValue;
+        ending: MoneyValue;
+    }>;
+}

package/dist/lib/features/enterprise/multi-path-funnels.d.ts

@@ -0,0 +1,327 @@
+/**
+ * @fileoverview Enterprise - Multi-Path Funnels & Micro-Conversions
+ * @module features/enterprise/multi-path-funnels
+ *
+ * @description
+ * Track complex user journeys and micro-conversions with support
+ * for non-linear funnel analysis and segment-based drop-off.
+ *
+ * @useCases
+ * - Define multi-path funnels
+ * - Track micro-conversions
+ * - Analyze drop-off by segment
+ * - Non-linear journey tracking
+ * - Onboarding step analysis
+ *
+ * @metrics
+ * - Path completion rates
+ * - Micro-conversion rates
+ * - Drop-off by segment
+ * - Time between steps
+ * - Alternative path analysis
+ *
+ * @chartData
+ * - Sankey diagram: User flow paths
+ * - Funnel chart: Multi-path visualization
+ * - Heatmap: Drop-off by segment
+ * - Timeline: Step progression
+ *
+ * @example
+ * ```typescript
+ * const funnels = new MultiPathFunnels(webId, endpoint, apiKey);
+ *
+ * // Define a multi-path funnel
+ * await funnels.defineFunnel({
+ *   name: 'Onboarding',
+ *   paths: [
+ *     { steps: ['signup', 'profile', 'first_action'] },
+ *     { steps: ['signup', 'skip_profile', 'first_action'] }
+ *   ]
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Funnel path definition.
+ */
+export interface FunnelPath {
+    /** Path identifier */
+    pathId?: string;
+    /** Path name */
+    name?: string;
+    /** Ordered list of step events */
+    steps: string[];
+    /** Whether steps must be in order */
+    ordered?: boolean;
+    /** Maximum time window between first and last step */
+    timeWindowMs?: number;
+}
+/**
+ * Multi-path funnel definition.
+ */
+export interface MultiPathFunnelDefinition {
+    /** Funnel identifier */
+    funnelId?: string;
+    /** Funnel name */
+    name: string;
+    /** Funnel description */
+    description?: string;
+    /** Alternative paths to conversion */
+    paths: FunnelPath[];
+    /** Micro-conversion definitions */
+    microConversions?: MicroConversionDefinition[];
+    /** Goal event (final conversion) */
+    goalEvent: string;
+}
+/**
+ * Micro-conversion definition.
+ */
+export interface MicroConversionDefinition {
+    /** Micro-conversion identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Event that triggers this micro-conversion */
+    event: string;
+    /** Weight/importance (0-1) */
+    weight?: number;
+    /** Prerequisite micro-conversions */
+    prerequisites?: string[];
+}
+/**
+ * Funnel step tracking configuration.
+ */
+export interface MultiPathStepConfig {
+    /** Funnel ID */
+    funnelId: string;
+    /** Step/event name */
+    step: string;
+    /** User ID */
+    userId: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Path ID (if known) */
+    pathId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Micro-conversion tracking configuration.
+ */
+export interface MicroConversionConfig {
+    /** Micro-conversion ID */
+    conversionId: string;
+    /** User ID */
+    userId: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Value associated with conversion */
+    value?: number;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Funnel analysis configuration.
+ */
+export interface FunnelAnalysisConfig {
+    /** Funnel ID */
+    funnelId: string;
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Segment by attribute */
+    segmentBy?: string;
+    /** Include path breakdown */
+    includePaths?: boolean;
+    /** Include micro-conversions */
+    includeMicroConversions?: boolean;
+}
+/**
+ * Path analysis result.
+ */
+export interface PathAnalysis {
+    pathId: string;
+    pathName: string;
+    steps: string[];
+    userCount: number;
+    completionRate: number;
+    avgTimeToComplete: number;
+    stepAnalysis: Array<{
+        step: string;
+        entered: number;
+        completed: number;
+        dropOffRate: number;
+        avgTimeSpent: number;
+    }>;
+}
+/**
+ * Micro-conversion analysis.
+ */
+export interface MicroConversionAnalysis {
+    id: string;
+    name: string;
+    completions: number;
+    completionRate: number;
+    avgValue: number;
+    correlation: number;
+}
+/**
+ * Multi-path funnel analysis result.
+ */
+export interface MultiPathFunnelAnalysis {
+    funnelId: string;
+    funnelName: string;
+    totalUsers: number;
+    goalCompletions: number;
+    overallConversionRate: number;
+    paths: PathAnalysis[];
+    microConversions?: MicroConversionAnalysis[];
+    topDropOffPoints: Array<{
+        step: string;
+        dropOffRate: number;
+        userCount: number;
+    }>;
+    avgTimeToConversion: number;
+}
+/**
+ * Segment drop-off analysis.
+ */
+export interface SegmentDropOffAnalysis {
+    funnelId: string;
+    segmentAttribute: string;
+    segments: Array<{
+        segment: string;
+        conversionRate: number;
+        dropOffByStep: Array<{
+            step: string;
+            dropOffRate: number;
+        }>;
+    }>;
+    bestPerformingSegment: string;
+    worstPerformingSegment: string;
+}
+/**
+ * User journey configuration.
+ */
+export interface UserJourneyConfig {
+    /** User ID */
+    userId: string;
+    /** Funnel ID */
+    funnelId: string;
+    /** Date range */
+    filter?: DateRangeFilter;
+}
+/**
+ * User journey result.
+ */
+export interface UserJourney {
+    userId: string;
+    funnelId: string;
+    currentPath: string;
+    stepsCompleted: Array<{
+        step: string;
+        timestamp: string;
+        properties?: Record<string, unknown>;
+    }>;
+    microConversions: Array<{
+        id: string;
+        timestamp: string;
+    }>;
+    goalReached: boolean;
+    goalReachedAt?: string;
+    timeInFunnel: number;
+}
+/**
+ * Calculate funnel conversion rate.
+ */
+export declare function calculateConversionRate(entered: number, completed: number): number;
+/**
+ * Calculate drop-off rate between steps.
+ */
+export declare function calculateDropOffRate(previousStep: number, currentStep: number): number;
+/**
+ * Find the best performing path.
+ */
+export declare function findBestPath(paths: PathAnalysis[]): PathAnalysis | null;
+/**
+ * Calculate weighted micro-conversion score.
+ */
+export declare function calculateMicroConversionScore(completedConversions: MicroConversionAnalysis[], definitions: MicroConversionDefinition[]): number;
+/**
+ * Generate path ID from steps.
+ */
+export declare function generatePathId(steps: string[]): string;
+/**
+ * Multi-path funnels and micro-conversions class.
+ */
+export declare class MultiPathFunnels extends EnterpriseFTRPC {
+    /**
+     * Define a multi-path funnel.
+     */
+    defineFunnel(definition: MultiPathFunnelDefinition): Promise<{
+        funnelId: string;
+    }>;
+    /**
+     * Update funnel definition.
+     */
+    updateFunnel(funnelId: string, updates: Partial<MultiPathFunnelDefinition>): Promise<{
+        updated: boolean;
+    }>;
+    /**
+     * Delete funnel.
+     */
+    deleteFunnel(funnelId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Track funnel step.
+     */
+    trackStep(config: MultiPathStepConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track micro-conversion.
+     */
+    trackMicroConversion(config: MicroConversionConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track goal completion.
+     */
+    trackGoal(funnelId: string, userId: string, properties?: Record<string, unknown>): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Get funnel analysis.
+     */
+    analyzeFunnel(config: FunnelAnalysisConfig): Promise<MultiPathFunnelAnalysis>;
+    /**
+     * Get path comparison.
+     */
+    comparePaths(funnelId: string, filter?: DateRangeFilter): Promise<PathAnalysis[]>;
+    /**
+     * Get segment drop-off analysis.
+     */
+    getSegmentDropOff(funnelId: string, segmentAttribute: string, filter?: DateRangeFilter): Promise<SegmentDropOffAnalysis>;
+    /**
+     * Get user journey.
+     */
+    getUserJourney(config: UserJourneyConfig): Promise<UserJourney>;
+    /**
+     * Get micro-conversion analysis.
+     */
+    getMicroConversionAnalysis(funnelId: string, filter?: DateRangeFilter): Promise<MicroConversionAnalysis[]>;
+    /**
+     * Get funnel trend.
+     */
+    getFunnelTrend(funnelId: string, filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * List all funnels.
+     */
+    listFunnels(): Promise<Array<{
+        funnelId: string;
+        name: string;
+        pathCount: number;
+        createdAt: string;
+    }>>;
+}