kanmi-perf-revenue 1.0.0 → 1.2.0

package/dist/empirical/datadog-product-analytics.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Datadog Product Analytics Integration
+ *
+ * Queries Datadog Product Analytics for enhanced user behavior data:
+ * - Conversion funnels with drop-off analysis
+ * - Cohort retention analysis
+ * - User journey mapping
+ * - Frustration signals (rage clicks, error clicks, dead clicks)
+ *
+ * Product Analytics uses the same SDK as RUM, providing unified
+ * performance + behavior data without needing Google Analytics.
+ *
+ * @author Kanmi Obasa <i@kanmiobasa.com>
+ */
+import type { SessionData, DatadogQueryConfig } from './datadog-session-query.js';
+export interface ProductAnalyticsConfig extends DatadogQueryConfig {
+    /** Application ID for Product Analytics */
+    applicationId?: string;
+    /** Include frustration signals */
+    includeFrustrationSignals?: boolean;
+    /** Include retention metrics */
+    includeRetention?: boolean;
+}
+export interface FrustrationSignals {
+    /** Rage clicks (rapid repeated clicks on same element) */
+    rageClicks: number;
+    /** Dead clicks (clicks on non-interactive elements) */
+    deadClicks: number;
+    /** Error clicks (clicks that triggered JS errors) */
+    errorClicks: number;
+    /** Total frustration score (weighted sum) */
+    frustrationScore: number;
+}
+export interface EnhancedSessionData extends SessionData {
+    /** Frustration signals from user behavior */
+    frustration?: FrustrationSignals;
+    /** Session replay available */
+    hasReplay?: boolean;
+    /** User engagement score (0-100) */
+    engagementScore?: number;
+    /** Actions taken in session */
+    actions?: UserAction[];
+    /** Errors encountered */
+    errors?: SessionError[];
+}
+export interface UserAction {
+    type: 'click' | 'scroll' | 'input' | 'custom';
+    name: string;
+    timestamp: string;
+    target?: string;
+    frustrationSignal?: 'rage_click' | 'dead_click' | 'error_click';
+}
+export interface SessionError {
+    message: string;
+    source: string;
+    timestamp: string;
+    handled: boolean;
+}
+export interface FunnelStep {
+    name: string;
+    /** CSS selector or action name to match */
+    selector: string;
+    /** Whether this is a conversion event */
+    isConversion?: boolean;
+}
+export interface FunnelResult {
+    steps: FunnelStepResult[];
+    overallConversionRate: number;
+    totalSessions: number;
+    medianTimeToConvert: number | null;
+}
+export interface FunnelStepResult {
+    name: string;
+    sessions: number;
+    conversionRate: number;
+    dropOffRate: number;
+    avgTimeToNext: number | null;
+    /** Performance at this step */
+    performance: {
+        p75Lcp: number | null;
+        p75Inp: number | null;
+        frustrationRate: number;
+    };
+}
+export interface CohortDefinition {
+    /** Cohort name */
+    name: string;
+    /** Filter query (Datadog query syntax) */
+    query: string;
+    /** Time period for cohort */
+    period?: {
+        start: string;
+        end: string;
+    };
+}
+export interface RetentionResult {
+    cohort: string;
+    initialUsers: number;
+    /** Retention by period (day/week/month) */
+    retention: RetentionPeriod[];
+    /** Average LTV per user */
+    avgLtv: number;
+}
+export interface RetentionPeriod {
+    period: number;
+    label: string;
+    usersReturned: number;
+    retentionRate: number;
+    revenue: number;
+}
+export interface JourneyNode {
+    page: string;
+    sessions: number;
+    avgTimeSpent: number;
+    exitRate: number;
+    nextPages: Array<{
+        page: string;
+        probability: number;
+    }>;
+}
+export interface UserJourneyMap {
+    entryPoints: JourneyNode[];
+    totalJourneys: number;
+    avgJourneyLength: number;
+    commonPaths: Array<{
+        path: string[];
+        count: number;
+        conversionRate: number;
+    }>;
+}
+/**
+ * Query Datadog for enhanced session data including frustration signals.
+ */
+export declare function queryEnhancedSessions(config: ProductAnalyticsConfig): Promise<{
+    sessions: EnhancedSessionData[];
+    metadata: Record<string, unknown>;
+}>;
+/**
+ * Query and analyze a conversion funnel.
+ */
+export declare function queryFunnel(config: ProductAnalyticsConfig, steps: FunnelStep[]): Promise<FunnelResult>;
+/**
+ * Analyze funnel with performance correlation.
+ */
+export declare function analyzeFunnelPerformanceImpact(funnel: FunnelResult, _sessions: EnhancedSessionData[]): {
+    stepAnalysis: Array<{
+        step: string;
+        fastSessions: {
+            count: number;
+            conversionRate: number;
+        };
+        slowSessions: {
+            count: number;
+            conversionRate: number;
+        };
+        performanceImpact: number;
+    }>;
+    recommendations: string[];
+};
+/**
+ * Query cohort retention data.
+ */
+export declare function queryCohortRetention(config: ProductAnalyticsConfig, cohort: CohortDefinition, periods?: number, periodType?: 'day' | 'week' | 'month'): Promise<RetentionResult>;
+/**
+ * Build user journey map from session data.
+ */
+export declare function buildUserJourneyMap(sessions: EnhancedSessionData[]): UserJourneyMap;
+/**
+ * Analyze frustration signals and their impact on conversions.
+ */
+export declare function analyzeFrustrationImpact(sessions: EnhancedSessionData[]): {
+    summary: {
+        totalSessions: number;
+        frustratedSessions: number;
+        frustrationRate: number;
+        conversionWithFrustration: number;
+        conversionWithoutFrustration: number;
+        conversionImpact: number;
+    };
+    bySignalType: Array<{
+        type: string;
+        count: number;
+        sessionsAffected: number;
+        conversionRate: number;
+    }>;
+    recommendations: string[];
+};
+/**
+ * Generate markdown report for Product Analytics data.
+ */
+export declare function generateProductAnalyticsMarkdown(sessions: EnhancedSessionData[], funnel?: FunnelResult, retention?: RetentionResult): string;
+//# sourceMappingURL=datadog-product-analytics.d.ts.map

package/dist/empirical/datadog-product-analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datadog-product-analytics.d.ts","sourceRoot":"","sources":["../../src/empirical/datadog-product-analytics.ts"],"names":[],"mappings":"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"}