flowgrid-sdk 1.0.0

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

@@ -0,0 +1,288 @@
+/**
+ * @fileoverview Enterprise - Churn & Predictive Analytics
+ * @module features/enterprise/churn
+ *
+ * @description
+ * Predict and measure churn proactively using usage patterns,
+ * engagement signals, and predictive scoring models.
+ *
+ * @useCases
+ * - Detect usage decay patterns
+ * - Identify at-risk users
+ * - Predict churn probability
+ * - Correlate NPS with churn
+ * - Track churn prevention success
+ *
+ * @metrics
+ * - Churn rate
+ * - Churn risk score
+ * - Days to churn prediction
+ * - At-risk user count
+ * - Prevention success rate
+ *
+ * @chartData
+ * - Line chart: Churn rate over time
+ * - Distribution: Risk score distribution
+ * - Bar chart: Churn by segment
+ * - Funnel: Churn prevention funnel
+ *
+ * @example
+ * ```typescript
+ * const churn = new ChurnAnalytics(webId, endpoint, apiKey);
+ *
+ * // Get user churn risk
+ * const risk = await churn.getUserRiskScore('user_123');
+ *
+ * // Get at-risk users
+ * const atRisk = await churn.getAtRiskUsers({ minScore: 70 });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Churn risk factors.
+ */
+export interface ChurnRiskFactors {
+    /** Days since last activity */
+    daysSinceLastActivity: number;
+    /** Usage trend (negative = declining) */
+    usageTrend: number;
+    /** Session frequency change */
+    sessionFrequencyChange: number;
+    /** Feature usage breadth change */
+    featureUsageChange: number;
+    /** Support tickets opened */
+    supportTickets: number;
+    /** NPS score (if available) */
+    npsScore?: number;
+    /** Payment failures */
+    paymentFailures: number;
+    /** Contract/subscription end approaching */
+    daysUntilRenewal?: number;
+}
+/**
+ * Churn risk score result.
+ */
+export interface ChurnRiskScore {
+    /** User ID */
+    userId: string;
+    /** Risk score (0-100, higher = more likely to churn) */
+    score: number;
+    /** Risk level classification */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Predicted days until churn */
+    predictedDaysToChurn?: number;
+    /** Top contributing factors */
+    topFactors: Array<{
+        factor: string;
+        contribution: number;
+        value: unknown;
+    }>;
+    /** Recommended actions */
+    recommendations: string[];
+    /** Last updated */
+    updatedAt: string;
+}
+/**
+ * Usage decay configuration.
+ */
+export interface UsageDecayConfig {
+    /** User ID */
+    userId: string;
+    /** Metric to track decay */
+    metric: 'sessions' | 'events' | 'features' | 'time_spent';
+    /** Comparison periods */
+    periods: {
+        current: DateRangeFilter;
+        previous: DateRangeFilter;
+    };
+}
+/**
+ * Usage decay result.
+ */
+export interface UsageDecay {
+    userId: string;
+    metric: string;
+    currentValue: number;
+    previousValue: number;
+    changePercent: number;
+    isDecaying: boolean;
+    decayRate: number;
+}
+/**
+ * NPS tracking configuration.
+ */
+export interface NPSConfig {
+    /** User ID */
+    userId: string;
+    /** NPS score (0-10) */
+    score: number;
+    /** Feedback comment */
+    feedback?: string;
+    /** Survey context */
+    context?: string;
+}
+/**
+ * Churn event configuration.
+ */
+export interface ChurnEventConfig {
+    /** User ID */
+    userId: string;
+    /** Churn type */
+    churnType: 'voluntary' | 'involuntary' | 'downgrade';
+    /** Churn reason */
+    reason?: string;
+    /** Subscription/account value lost */
+    valueLost?: {
+        amount: number;
+        currency: string;
+    };
+    /** Win-back attempted */
+    winbackAttempted?: boolean;
+}
+/**
+ * Prevention action configuration.
+ */
+export interface PreventionActionConfig {
+    /** User ID */
+    userId: string;
+    /** Action type */
+    actionType: 'outreach' | 'discount' | 'feature_unlock' | 'support_call' | 'other';
+    /** Action details */
+    details?: Record<string, unknown>;
+    /** Outcome */
+    outcome?: 'success' | 'pending' | 'failed';
+}
+/**
+ * At-risk users filter.
+ */
+export interface AtRiskUsersFilter extends DateRangeFilter {
+    /** Minimum risk score */
+    minScore?: number;
+    /** Risk level filter */
+    riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+    /** User segment */
+    segment?: string;
+    /** Limit results */
+    limit?: number;
+}
+/**
+ * Churn analytics result.
+ */
+export interface ChurnAnalyticsResult {
+    /** Total churn rate */
+    churnRate: number;
+    /** Voluntary churn rate */
+    voluntaryChurnRate: number;
+    /** Involuntary churn rate */
+    involuntaryChurnRate: number;
+    /** At-risk user count */
+    atRiskUserCount: number;
+    /** Revenue at risk */
+    revenueAtRisk: {
+        amount: number;
+        currency: string;
+    };
+    /** Prevention success rate */
+    preventionSuccessRate: number;
+    /** Average NPS of churned users */
+    avgChurnedNPS: number;
+    /** Top churn reasons */
+    topReasons: Array<{
+        reason: string;
+        count: number;
+        percentage: number;
+    }>;
+    /** Churn trend */
+    trend: TimeSeriesData;
+}
+/**
+ * Calculate churn risk score from factors.
+ */
+export declare function calculateChurnRiskScore(factors: ChurnRiskFactors): number;
+/**
+ * Classify risk level from score.
+ */
+export declare function classifyRiskLevel(score: number): 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Generate churn prevention recommendations.
+ */
+export declare function generateRecommendations(riskFactors: Array<{
+    factor: string;
+    contribution: number;
+}>): string[];
+/**
+ * Churn and predictive analytics class.
+ */
+export declare class ChurnAnalytics extends EnterpriseFTRPC {
+    /**
+     * Get user churn risk score.
+     */
+    getUserRiskScore(userId: string): Promise<ChurnRiskScore>;
+    /**
+     * Get multiple users' risk scores.
+     */
+    getBulkRiskScores(userIds: string[]): Promise<ChurnRiskScore[]>;
+    /**
+     * Get at-risk users.
+     */
+    getAtRiskUsers(filter?: AtRiskUsersFilter): Promise<ChurnRiskScore[]>;
+    /**
+     * Track usage decay.
+     */
+    trackUsageDecay(config: UsageDecayConfig): Promise<UsageDecay>;
+    /**
+     * Track NPS score.
+     */
+    trackNPS(config: NPSConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track churn event.
+     */
+    trackChurn(config: ChurnEventConfig): Promise<{
+        tracked: boolean;
+        churnId: string;
+    }>;
+    /**
+     * Track churn prevention action.
+     */
+    trackPreventionAction(config: PreventionActionConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Update prevention action outcome.
+     */
+    updatePreventionOutcome(userId: string, actionType: string, outcome: 'success' | 'failed'): Promise<{
+        updated: boolean;
+    }>;
+    /**
+     * Get churn analytics.
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<ChurnAnalyticsResult>;
+    /**
+     * Get churn rate trend.
+     */
+    getChurnTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get churn by segment.
+     */
+    getChurnBySegment(segmentAttribute: string, filter?: DateRangeFilter): Promise<Array<{
+        segment: string;
+        churnRate: number;
+        count: number;
+    }>>;
+    /**
+     * Get NPS trend.
+     */
+    getNPSTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get prevention effectiveness.
+     */
+    getPreventionEffectiveness(filter?: DateRangeFilter): Promise<Array<{
+        actionType: string;
+        attempts: number;
+        successes: number;
+        rate: number;
+    }>>;
+}

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

@@ -0,0 +1,270 @@
+/**
+ * @fileoverview Enterprise - Advanced Cohorts & Segmentation
+ * @module features/enterprise/cohorts
+ *
+ * @description
+ * Generate behavioral and acquisition cohorts for granular analysis.
+ * Segment users by behavior, acquisition source, and custom criteria.
+ *
+ * @useCases
+ * - Create behavior-based cohorts
+ * - Segment by acquisition source
+ * - Track paid vs free user cohorts
+ * - Dynamic segmentation rules
+ * - Cohort comparison analysis
+ *
+ * @metrics
+ * - Cohort size
+ * - Cohort retention
+ * - Cohort conversion
+ * - Segment growth rate
+ * - Cross-segment behavior
+ *
+ * @chartData
+ * - Bar chart: Cohort sizes
+ * - Line chart: Cohort trends
+ * - Heatmap: Cohort retention matrix
+ * - Comparison: Cohort A vs B
+ *
+ * @example
+ * ```typescript
+ * const cohorts = new Cohorts(webId, endpoint, apiKey);
+ *
+ * // Create a behavioral cohort
+ * await cohorts.createCohort({
+ *   name: 'Power Users',
+ *   type: 'behavioral',
+ *   rules: [{ attribute: 'sessions_per_week', operator: 'gte', value: 5 }]
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Cohort rule operators.
+ */
+export type CohortOperator = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'between' | 'exists' | 'not_exists';
+/**
+ * Cohort rule definition.
+ */
+export interface CohortRule {
+    /** Attribute to evaluate */
+    attribute: string;
+    /** Comparison operator */
+    operator: CohortOperator;
+    /** Value to compare against */
+    value: unknown;
+    /** Logical operator for combining rules */
+    logicalOperator?: 'and' | 'or';
+}
+/**
+ * Cohort type classification.
+ */
+export type CohortType = 'behavioral' | 'acquisition' | 'demographic' | 'lifecycle' | 'custom';
+/**
+ * Cohort definition configuration.
+ */
+export interface CohortDefinition {
+    /** Unique cohort identifier */
+    cohortId?: string;
+    /** Cohort name */
+    name: string;
+    /** Cohort description */
+    description?: string;
+    /** Cohort type */
+    type: CohortType;
+    /** Rules for cohort membership */
+    rules: CohortRule[];
+    /** Whether cohort membership is dynamic */
+    dynamic?: boolean;
+    /** Time window for evaluation (for behavioral cohorts) */
+    timeWindow?: {
+        value: number;
+        unit: 'hours' | 'days' | 'weeks' | 'months';
+    };
+}
+/**
+ * Segment definition configuration.
+ */
+export interface SegmentDefinition {
+    /** Segment identifier */
+    segmentId?: string;
+    /** Segment name */
+    name: string;
+    /** Segment description */
+    description?: string;
+    /** Segmentation attribute */
+    attribute: string;
+    /** Segment values/buckets */
+    buckets: Array<{
+        name: string;
+        rules: CohortRule[];
+    }>;
+}
+/**
+ * User cohort assignment.
+ */
+export interface CohortAssignment {
+    /** User ID */
+    userId: string;
+    /** Cohort ID */
+    cohortId: string;
+    /** Assignment timestamp */
+    assignedAt: string;
+    /** Whether user currently matches cohort rules */
+    isActive: boolean;
+}
+/**
+ * Cohort comparison configuration.
+ */
+export interface CohortComparisonConfig {
+    /** First cohort ID */
+    cohortA: string;
+    /** Second cohort ID */
+    cohortB: string;
+    /** Metrics to compare */
+    metrics: string[];
+    /** Date range for comparison */
+    filter?: DateRangeFilter;
+}
+/**
+ * Cohort analytics filter.
+ */
+export interface CohortAnalyticsFilter extends DateRangeFilter {
+    /** Filter by cohort type */
+    type?: CohortType;
+    /** Minimum cohort size */
+    minSize?: number;
+}
+/**
+ * Cohort response from API.
+ */
+export interface CohortResponse {
+    cohortId: string;
+    name: string;
+    type: CohortType;
+    size: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Cohort member.
+ */
+export interface CohortMember {
+    userId: string;
+    joinedAt: string;
+    traits: Record<string, unknown>;
+    isActive: boolean;
+}
+/**
+ * Cohort analytics result.
+ */
+export interface CohortAnalytics {
+    cohortId: string;
+    name: string;
+    currentSize: number;
+    growthRate: number;
+    retention: {
+        day1: number;
+        day7: number;
+        day30: number;
+    };
+    conversion: number;
+    avgEngagementScore: number;
+}
+/**
+ * Cohort comparison result.
+ */
+export interface CohortComparison {
+    cohortA: CohortAnalytics;
+    cohortB: CohortAnalytics;
+    differences: Record<string, {
+        cohortAValue: number;
+        cohortBValue: number;
+        percentDiff: number;
+        significant: boolean;
+    }>;
+}
+/**
+ * Evaluate if a user matches cohort rules.
+ */
+export declare function evaluateCohortRules(userAttributes: Record<string, unknown>, rules: CohortRule[]): boolean;
+/**
+ * Generate cohort ID from name.
+ */
+export declare function generateCohortId(name: string): string;
+/**
+ * Advanced cohorts and segmentation class.
+ */
+export declare class Cohorts extends EnterpriseFTRPC {
+    /**
+     * Create a new cohort.
+     */
+    createCohort(definition: CohortDefinition): Promise<CohortResponse>;
+    /**
+     * Update an existing cohort.
+     */
+    updateCohort(cohortId: string, updates: Partial<CohortDefinition>): Promise<CohortResponse>;
+    /**
+     * Delete a cohort.
+     */
+    deleteCohort(cohortId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Get cohort by ID.
+     */
+    getCohort(cohortId: string): Promise<CohortResponse & {
+        rules: CohortRule[];
+    }>;
+    /**
+     * List all cohorts.
+     */
+    listCohorts(filter?: CohortAnalyticsFilter): Promise<CohortResponse[]>;
+    /**
+     * Get cohort members.
+     */
+    getCohortMembers(cohortId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        members: CohortMember[];
+        total: number;
+    }>;
+    /**
+     * Check if user belongs to cohort.
+     */
+    isUserInCohort(userId: string, cohortId: string): Promise<{
+        isMember: boolean;
+    }>;
+    /**
+     * Get user's cohorts.
+     */
+    getUserCohorts(userId: string): Promise<CohortAssignment[]>;
+    /**
+     * Create a segment.
+     */
+    createSegment(definition: SegmentDefinition): Promise<{
+        segmentId: string;
+    }>;
+    /**
+     * Get segment distribution.
+     */
+    getSegmentDistribution(segmentId: string, filter?: DateRangeFilter): Promise<Array<{
+        bucket: string;
+        count: number;
+        percentage: number;
+    }>>;
+    /**
+     * Compare two cohorts.
+     */
+    compareCohorts(config: CohortComparisonConfig): Promise<CohortComparison>;
+    /**
+     * Get cohort analytics.
+     */
+    getCohortAnalytics(cohortId: string, filter?: DateRangeFilter): Promise<CohortAnalytics>;
+    /**
+     * Get cohort growth trend.
+     */
+    getCohortGrowth(cohortId: string, filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+}