flowgrid-sdk 1.0.0

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

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview Enterprise - Marketing & Acquisition Analytics
+ * @module features/enterprise/acquisition
+ *
+ * @description
+ * Deep attribution and acquisition insights including CAC breakdown,
+ * trial-to-paid funnel tracking, and campaign performance by cohort.
+ *
+ * @useCases
+ * - Track customer acquisition cost by channel
+ * - Monitor trial → paid → upgrade funnel
+ * - Analyze campaign performance
+ * - Multi-touch attribution
+ * - Marketing ROI calculation
+ *
+ * @metrics
+ * - Customer Acquisition Cost (CAC)
+ * - Trial conversion rate
+ * - Paid conversion rate
+ * - Campaign ROI
+ * - Channel effectiveness
+ *
+ * @chartData
+ * - Bar chart: CAC by channel
+ * - Funnel: Trial to paid conversion
+ * - Line chart: Campaign performance
+ * - Pie chart: Acquisition source mix
+ *
+ * @example
+ * ```typescript
+ * const acquisition = new AcquisitionAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track acquisition
+ * await acquisition.trackAcquisition({
+ *   userId: 'user_123',
+ *   source: 'google_ads',
+ *   campaign: 'summer_2026'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity, MoneyValue, CurrencyCode } from "../../types";
+/**
+ * Acquisition source types.
+ */
+export type AcquisitionSource = 'organic' | 'paid_search' | 'paid_social' | 'organic_social' | 'email' | 'referral' | 'affiliate' | 'direct' | 'content' | 'other';
+/**
+ * User lifecycle stage.
+ */
+export type LifecycleStage = 'visitor' | 'lead' | 'trial' | 'paid' | 'churned' | 'resurrected';
+/**
+ * Acquisition tracking configuration.
+ */
+export interface AcquisitionConfig {
+    /** User ID */
+    userId: string;
+    /** Acquisition source */
+    source: AcquisitionSource;
+    /** Campaign name/ID */
+    campaign?: string;
+    /** Medium */
+    medium?: string;
+    /** Channel */
+    channel?: string;
+    /** Referring URL */
+    referrer?: string;
+    /** Landing page */
+    landingPage?: string;
+    /** UTM parameters */
+    utmParams?: {
+        source?: string;
+        medium?: string;
+        campaign?: string;
+        term?: string;
+        content?: string;
+    };
+    /** Acquisition cost (if known) */
+    cost?: MoneyValue;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Campaign definition.
+ */
+export interface CampaignDefinition {
+    /** Campaign ID */
+    campaignId: string;
+    /** Campaign name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Start date */
+    startDate: string;
+    /** End date */
+    endDate?: string;
+    /** Budget */
+    budget: MoneyValue;
+    /** Target acquisition count */
+    targetAcquisitions?: number;
+    /** Channel */
+    channel: AcquisitionSource;
+    /** Tags */
+    tags?: string[];
+}
+/**
+ * Campaign spend tracking.
+ */
+export interface CampaignSpendConfig {
+    /** Campaign ID */
+    campaignId: string;
+    /** Spend amount */
+    amount: MoneyValue;
+    /** Spend date */
+    date: string;
+    /** Impressions */
+    impressions?: number;
+    /** Clicks */
+    clicks?: number;
+}
+/**
+ * Lifecycle transition configuration.
+ */
+export interface LifecycleTransitionConfig {
+    /** User ID */
+    userId: string;
+    /** Previous stage */
+    fromStage: LifecycleStage;
+    /** New stage */
+    toStage: LifecycleStage;
+    /** Revenue associated (if applicable) */
+    revenue?: MoneyValue;
+}
+/**
+ * CAC configuration.
+ */
+export interface CACConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Breakdown dimension */
+    breakdown?: 'channel' | 'campaign' | 'source';
+    /** Include only paid channels */
+    paidOnly?: boolean;
+}
+/**
+ * CAC result.
+ */
+export interface CACResult {
+    /** Overall CAC */
+    cac: MoneyValue;
+    /** Total spend */
+    totalSpend: MoneyValue;
+    /** Total acquisitions */
+    totalAcquisitions: number;
+    /** Breakdown (if requested) */
+    breakdown?: Array<{
+        dimension: string;
+        cac: MoneyValue;
+        spend: MoneyValue;
+        acquisitions: number;
+    }>;
+}
+/**
+ * Trial funnel configuration.
+ */
+export interface TrialFunnelConfig {
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Segment by attribute */
+    segmentBy?: string;
+}
+/**
+ * Trial funnel result.
+ */
+export interface TrialFunnelResult {
+    /** Visitors */
+    visitors: number;
+    /** Signups */
+    signups: number;
+    /** Trial starts */
+    trialStarts: number;
+    /** Trial to paid conversions */
+    trialToPaid: number;
+    /** Paid upgrades */
+    upgrades: number;
+    /** Conversion rates */
+    rates: {
+        visitorToSignup: number;
+        signupToTrial: number;
+        trialToPaid: number;
+        paidToUpgrade: number;
+        overallConversion: number;
+    };
+    /** Average time in trial */
+    avgTrialDays: number;
+}
+/**
+ * Campaign performance result.
+ */
+export interface CampaignPerformance {
+    campaignId: string;
+    name: string;
+    spend: MoneyValue;
+    impressions: number;
+    clicks: number;
+    acquisitions: number;
+    revenue: MoneyValue;
+    metrics: {
+        ctr: number;
+        cpc: MoneyValue;
+        cpa: MoneyValue;
+        roas: number;
+        roi: number;
+    };
+    trend: 'improving' | 'stable' | 'declining';
+}
+/**
+ * Attribution model types.
+ */
+export type AttributionModel = 'first_touch' | 'last_touch' | 'linear' | 'time_decay' | 'position_based';
+/**
+ * Attribution analysis configuration.
+ */
+export interface AttributionAnalysisConfig {
+    /** Attribution model */
+    model: AttributionModel;
+    /** Date range */
+    filter?: DateRangeFilter;
+    /** Conversion event */
+    conversionEvent?: string;
+}
+/**
+ * Attribution result.
+ */
+export interface AttributionResult {
+    model: AttributionModel;
+    channels: Array<{
+        channel: string;
+        conversions: number;
+        revenue: MoneyValue;
+        contribution: number;
+    }>;
+    touchpointAnalysis: {
+        avgTouchpoints: number;
+        avgDaysToConvert: number;
+        topPaths: Array<{
+            path: string[];
+            count: number;
+            conversionRate: number;
+        }>;
+    };
+}
+/**
+ * Acquisition analytics result.
+ */
+export interface AcquisitionAnalytics {
+    totalAcquisitions: number;
+    cac: MoneyValue;
+    ltv: MoneyValue;
+    ltvCacRatio: number;
+    topChannels: Array<{
+        channel: AcquisitionSource;
+        acquisitions: number;
+        percentage: number;
+        cac: MoneyValue;
+    }>;
+    trialConversionRate: number;
+    paidConversionRate: number;
+    trend: TimeSeriesData;
+}
+/**
+ * Calculate CAC.
+ */
+export declare function calculateCAC(totalSpend: number, totalAcquisitions: number, currency: CurrencyCode): MoneyValue;
+/**
+ * Calculate ROAS (Return on Ad Spend).
+ */
+export declare function calculateROAS(revenue: number, spend: number): number;
+/**
+ * Calculate LTV:CAC ratio.
+ */
+export declare function calculateLTVCACRatio(ltv: number, cac: number): number;
+/**
+ * Parse UTM parameters from URL.
+ */
+export declare function parseUTMParams(url: string): Record<string, string>;
+/**
+ * Classify acquisition source from UTM parameters.
+ */
+export declare function classifySource(utmSource?: string, utmMedium?: string): AcquisitionSource;
+/**
+ * Marketing and acquisition analytics class.
+ */
+export declare class AcquisitionAnalytics extends EnterpriseFTRPC {
+    /**
+     * Track user acquisition.
+     */
+    trackAcquisition(config: AcquisitionConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track lifecycle transition.
+     */
+    trackLifecycleTransition(config: LifecycleTransitionConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Create campaign.
+     */
+    createCampaign(definition: CampaignDefinition): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Track campaign spend.
+     */
+    trackCampaignSpend(config: CampaignSpendConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Get CAC.
+     */
+    getCAC(config?: CACConfig): Promise<CACResult>;
+    /**
+     * Get trial funnel.
+     */
+    getTrialFunnel(config?: TrialFunnelConfig): Promise<TrialFunnelResult>;
+    /**
+     * Get campaign performance.
+     */
+    getCampaignPerformance(campaignId?: string, filter?: DateRangeFilter): Promise<CampaignPerformance[]>;
+    /**
+     * Get attribution analysis.
+     */
+    getAttribution(config: AttributionAnalysisConfig): Promise<AttributionResult>;
+    /**
+     * Get LTV:CAC ratio.
+     */
+    getLTVCACRatio(filter?: DateRangeFilter): Promise<{
+        ltv: MoneyValue;
+        cac: MoneyValue;
+        ratio: number;
+        healthy: boolean;
+    }>;
+    /**
+     * Get acquisition analytics.
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<AcquisitionAnalytics>;
+    /**
+     * Get acquisition trend.
+     */
+    getAcquisitionTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get channel effectiveness.
+     */
+    getChannelEffectiveness(filter?: DateRangeFilter): Promise<Array<{
+        channel: AcquisitionSource;
+        acquisitions: number;
+        cac: MoneyValue;
+        ltv: MoneyValue;
+        paybackMonths: number;
+        score: number;
+    }>>;
+    /**
+     * Get cohort-based campaign analysis.
+     */
+    getCohortCampaignAnalysis(campaignId: string, periods: number): Promise<{
+        cohorts: Array<{
+            cohortDate: string;
+            acquisitions: number;
+            retention: number[];
+            ltv: MoneyValue;
+        }>;
+    }>;
+}

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

@@ -0,0 +1,348 @@
+/**
+ * @fileoverview Enterprise - Alerts & Anomaly Detection
+ * @module features/enterprise/alerts
+ *
+ * @description
+ * Proactively monitor anomalies in key metrics and trigger alerts.
+ * Detect activation drops, error spikes, and custom threshold breaches.
+ *
+ * @useCases
+ * - Monitor for activation drops
+ * - Detect error/churn spikes
+ * - Set custom alert rules
+ * - Threshold monitoring
+ * - Real-time anomaly detection
+ *
+ * @metrics
+ * - Alert frequency
+ * - Time to detection
+ * - False positive rate
+ * - Alert resolution time
+ * - Metric anomaly score
+ *
+ * @chartData
+ * - Line chart: Metric with anomaly markers
+ * - Timeline: Alert history
+ * - Bar chart: Alerts by type
+ * - Dashboard: Alert status
+ *
+ * @example
+ * ```typescript
+ * const alerts = new AlertsAnalytics(webId, endpoint, apiKey);
+ *
+ * // Create an alert rule
+ * await alerts.createAlert({
+ *   name: 'Activation Drop',
+ *   metric: 'activation_rate',
+ *   condition: 'drops_below',
+ *   threshold: 50,
+ *   severity: 'high'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Alert condition types.
+ */
+export type AlertCondition = 'exceeds' | 'drops_below' | 'changes_by' | 'anomaly_detected' | 'no_data';
+/**
+ * Alert severity levels.
+ */
+export type AlertSeverity = 'info' | 'warning' | 'high' | 'critical';
+/**
+ * Alert status.
+ */
+export type AlertStatus = 'active' | 'acknowledged' | 'resolved' | 'muted';
+/**
+ * Notification channel.
+ */
+export type NotificationChannel = 'email' | 'slack' | 'webhook' | 'pagerduty' | 'sms';
+/**
+ * Alert rule definition.
+ */
+export interface AlertRuleDefinition {
+    /** Alert ID */
+    alertId?: string;
+    /** Alert name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Metric to monitor */
+    metric: string;
+    /** Condition type */
+    condition: AlertCondition;
+    /** Threshold value */
+    threshold: number;
+    /** Change percentage (for changes_by condition) */
+    changePercent?: number;
+    /** Comparison window */
+    window?: {
+        value: number;
+        unit: 'minutes' | 'hours' | 'days';
+    };
+    /** Alert severity */
+    severity: AlertSeverity;
+    /** Notification channels */
+    channels: NotificationChannel[];
+    /** Notification recipients */
+    recipients?: string[];
+    /** Custom filters */
+    filters?: Record<string, unknown>;
+    /** Is alert enabled */
+    enabled?: boolean;
+    /** Cooldown period (minutes) */
+    cooldownMinutes?: number;
+    /** Tags */
+    tags?: string[];
+}
+/**
+ * Alert instance (triggered alert).
+ */
+export interface AlertInstance {
+    /** Instance ID */
+    instanceId: string;
+    /** Alert rule ID */
+    alertId: string;
+    /** Alert name */
+    alertName: string;
+    /** Triggered at */
+    triggeredAt: string;
+    /** Current value that triggered alert */
+    currentValue: number;
+    /** Threshold value */
+    thresholdValue: number;
+    /** Severity */
+    severity: AlertSeverity;
+    /** Status */
+    status: AlertStatus;
+    /** Acknowledged by */
+    acknowledgedBy?: string;
+    /** Acknowledged at */
+    acknowledgedAt?: string;
+    /** Resolved at */
+    resolvedAt?: string;
+    /** Resolution notes */
+    resolutionNotes?: string;
+}
+/**
+ * Anomaly detection configuration.
+ */
+export interface AnomalyDetectionConfig {
+    /** Metric to analyze */
+    metric: string;
+    /** Lookback period */
+    lookbackDays: number;
+    /** Sensitivity (0-1, higher = more sensitive) */
+    sensitivity?: number;
+    /** Detection method */
+    method?: 'statistical' | 'ml' | 'hybrid';
+}
+/**
+ * Detected anomaly.
+ */
+export interface Anomaly {
+    /** Anomaly ID */
+    anomalyId: string;
+    /** Metric */
+    metric: string;
+    /** Detected at */
+    detectedAt: string;
+    /** Expected value */
+    expectedValue: number;
+    /** Actual value */
+    actualValue: number;
+    /** Deviation percentage */
+    deviationPercent: number;
+    /** Anomaly score (0-1) */
+    anomalyScore: number;
+    /** Direction */
+    direction: 'up' | 'down';
+    /** Severity */
+    severity: AlertSeverity;
+    /** Is confirmed anomaly */
+    isConfirmed: boolean;
+}
+/**
+ * Alert notification configuration.
+ */
+export interface NotificationConfig {
+    /** Channel */
+    channel: NotificationChannel;
+    /** Channel-specific config */
+    config: {
+        /** Email addresses (for email channel) */
+        emails?: string[];
+        /** Slack webhook URL (for slack channel) */
+        slackWebhook?: string;
+        /** Webhook URL (for webhook channel) */
+        webhookUrl?: string;
+        /** PagerDuty routing key */
+        pagerDutyKey?: string;
+        /** Phone numbers (for SMS) */
+        phoneNumbers?: string[];
+    };
+}
+/**
+ * Alert analytics filter.
+ */
+export interface AlertAnalyticsFilter extends DateRangeFilter {
+    /** Filter by severity */
+    severity?: AlertSeverity;
+    /** Filter by status */
+    status?: AlertStatus;
+    /** Filter by metric */
+    metric?: string;
+}
+/**
+ * Alert analytics result.
+ */
+export interface AlertAnalytics {
+    /** Total alerts triggered */
+    totalAlerts: number;
+    /** By severity */
+    bySeverity: Record<AlertSeverity, number>;
+    /** By status */
+    byStatus: Record<AlertStatus, number>;
+    /** Average time to acknowledge (ms) */
+    avgTimeToAcknowledgeMs: number;
+    /** Average time to resolve (ms) */
+    avgTimeToResolveMs: number;
+    /** Top triggered alerts */
+    topAlerts: Array<{
+        alertId: string;
+        name: string;
+        count: number;
+    }>;
+    /** Alert trend */
+    trend: TimeSeriesData;
+}
+/**
+ * Calculate standard deviation.
+ */
+export declare function calculateStdDev(values: number[]): number;
+/**
+ * Calculate Z-score for anomaly detection.
+ */
+export declare function calculateZScore(value: number, mean: number, stdDev: number): number;
+/**
+ * Determine if value is anomalous based on Z-score.
+ */
+export declare function isAnomaly(zScore: number, sensitivity?: number): boolean;
+/**
+ * Calculate anomaly score (0-1).
+ */
+export declare function calculateAnomalyScore(zScore: number): number;
+/**
+ * Classify severity from anomaly score.
+ */
+export declare function classifySeverity(anomalyScore: number): AlertSeverity;
+/**
+ * Check if alert condition is met.
+ */
+export declare function checkAlertCondition(currentValue: number, condition: AlertCondition, threshold: number, previousValue?: number, changePercent?: number): boolean;
+/**
+ * Alerts and anomaly detection class.
+ */
+export declare class AlertsAnalytics extends EnterpriseFTRPC {
+    /**
+     * Create an alert rule.
+     */
+    createAlert(definition: AlertRuleDefinition): Promise<{
+        alertId: string;
+    }>;
+    /**
+     * Update an alert rule.
+     */
+    updateAlert(alertId: string, updates: Partial<AlertRuleDefinition>): Promise<{
+        updated: boolean;
+    }>;
+    /**
+     * Delete an alert rule.
+     */
+    deleteAlert(alertId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Enable/disable an alert.
+     */
+    toggleAlert(alertId: string, enabled: boolean): Promise<{
+        updated: boolean;
+    }>;
+    /**
+     * Get alert rule.
+     */
+    getAlert(alertId: string): Promise<AlertRuleDefinition & {
+        alertId: string;
+    }>;
+    /**
+     * List all alert rules.
+     */
+    listAlerts(enabled?: boolean): Promise<Array<AlertRuleDefinition & {
+        alertId: string;
+    }>>;
+    /**
+     * Get triggered alerts.
+     */
+    getTriggeredAlerts(filter?: AlertAnalyticsFilter): Promise<AlertInstance[]>;
+    /**
+     * Acknowledge an alert.
+     */
+    acknowledgeAlert(instanceId: string, acknowledgedBy: string): Promise<{
+        acknowledged: boolean;
+    }>;
+    /**
+     * Resolve an alert.
+     */
+    resolveAlert(instanceId: string, notes?: string): Promise<{
+        resolved: boolean;
+    }>;
+    /**
+     * Mute an alert temporarily.
+     */
+    muteAlert(alertId: string, durationMinutes: number): Promise<{
+        muted: boolean;
+    }>;
+    /**
+     * Run anomaly detection.
+     */
+    detectAnomalies(config: AnomalyDetectionConfig): Promise<Anomaly[]>;
+    /**
+     * Get historical anomalies.
+     */
+    getAnomalies(filter?: AlertAnalyticsFilter): Promise<Anomaly[]>;
+    /**
+     * Configure notification channel.
+     */
+    configureNotification(config: NotificationConfig): Promise<{
+        configured: boolean;
+    }>;
+    /**
+     * Test notification channel.
+     */
+    testNotification(channel: NotificationChannel): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get alert analytics.
+     */
+    getAnalytics(filter?: AlertAnalyticsFilter): Promise<AlertAnalytics>;
+    /**
+     * Get metric with anomaly overlay.
+     */
+    getMetricWithAnomalies(metric: string, filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<{
+        data: TimeSeriesData;
+        anomalies: Array<{
+            timestamp: string;
+            score: number;
+        }>;
+    }>;
+    /**
+     * Get alert correlation analysis.
+     */
+    getAlertCorrelation(filter?: DateRangeFilter): Promise<Array<{
+        alertPair: [string, string];
+        correlation: number;
+        coOccurrences: number;
+    }>>;
+}