kanmi-perf-revenue 1.0.0 → 1.1.0

package/dist/empirical/attribution.js

@@ -0,0 +1,305 @@
+/**
+ * Attribution Models
+ *
+ * First-touch vs last-touch session attribution for understanding
+ * how performance at different touchpoints affects conversions.
+ *
+ * @author Kanmi Obasa <i@kanmiobasa.com>
+ */
+// =============================================================================
+// CORE ATTRIBUTION
+// =============================================================================
+/**
+ * Build user journeys from session data.
+ */
+export function buildUserJourneys(sessions) {
+    // Group by user
+    const userMap = new Map();
+    for (const session of sessions) {
+        const userId = session.user_id || session.session_id;
+        if (!userMap.has(userId)) {
+            userMap.set(userId, []);
+        }
+        userMap.get(userId).push(session);
+    }
+    const journeys = [];
+    for (const [userId, userSessions] of userMap) {
+        // Sort by timestamp
+        const sorted = [...userSessions].sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+        const touchpoints = sorted.map(s => ({
+            timestamp: s.timestamp || '',
+            pageType: s.page_type || 'unknown',
+            trafficSource: s.traffic_source || 'unknown',
+            lcp: s.lcp_ms,
+            converted: s.has_purchase,
+            value: s.purchase_value,
+        }));
+        const converted = touchpoints.some(t => t.converted);
+        const totalValue = touchpoints.reduce((sum, t) => sum + t.value, 0);
+        journeys.push({
+            userId,
+            touchpoints,
+            converted,
+            totalValue,
+        });
+    }
+    return journeys;
+}
+/**
+ * Calculate attribution for all touchpoints.
+ */
+export function calculateAttribution(journeys, groupBy = 'pageType') {
+    const statsMap = new Map();
+    for (const journey of journeys) {
+        if (journey.touchpoints.length === 0)
+            continue;
+        // Get unique touchpoints in order
+        const touchpointOrder = journey.touchpoints.map(t => groupBy === 'pageType' ? t.pageType : t.trafficSource);
+        // Track sessions at each touchpoint
+        for (const tp of journey.touchpoints) {
+            const key = groupBy === 'pageType' ? tp.pageType : tp.trafficSource;
+            if (!statsMap.has(key)) {
+                statsMap.set(key, {
+                    sessions: 0,
+                    firstTouch: 0,
+                    lastTouch: 0,
+                    linear: 0,
+                    positionBased: 0,
+                    lcpValues: [],
+                    convertingJourneys: 0,
+                    totalJourneys: 0,
+                });
+            }
+            const stats = statsMap.get(key);
+            stats.sessions++;
+            if (tp.lcp !== null) {
+                stats.lcpValues.push(tp.lcp);
+            }
+        }
+        // Attribute conversions
+        if (journey.converted) {
+            const uniqueTouchpoints = [...new Set(touchpointOrder)];
+            const n = uniqueTouchpoints.length;
+            if (n === 0)
+                continue;
+            // First touch
+            const firstKey = touchpointOrder[0];
+            const firstStats = statsMap.get(firstKey);
+            if (firstStats) {
+                firstStats.firstTouch++;
+                firstStats.convertingJourneys++;
+            }
+            // Last touch
+            const lastKey = touchpointOrder[touchpointOrder.length - 1];
+            const lastStats = statsMap.get(lastKey);
+            if (lastStats) {
+                lastStats.lastTouch++;
+                if (lastKey !== firstKey) {
+                    lastStats.convertingJourneys++;
+                }
+            }
+            // Linear (equal credit)
+            const linearCredit = 1 / n;
+            for (const tp of uniqueTouchpoints) {
+                const stats = statsMap.get(tp);
+                if (stats) {
+                    stats.linear += linearCredit;
+                    if (tp !== firstKey && tp !== lastKey) {
+                        stats.convertingJourneys++;
+                    }
+                }
+            }
+            // Position-based (40% first, 40% last, 20% distributed)
+            for (let i = 0; i < uniqueTouchpoints.length; i++) {
+                const tp = uniqueTouchpoints[i];
+                const stats = statsMap.get(tp);
+                if (!stats)
+                    continue;
+                if (i === 0) {
+                    stats.positionBased += 0.4;
+                }
+                else if (i === uniqueTouchpoints.length - 1) {
+                    stats.positionBased += 0.4;
+                }
+                else {
+                    const middleShare = 0.2 / Math.max(1, uniqueTouchpoints.length - 2);
+                    stats.positionBased += middleShare;
+                }
+            }
+        }
+        // Track total journeys through each touchpoint
+        for (const tp of new Set(touchpointOrder)) {
+            const stats = statsMap.get(tp);
+            if (stats) {
+                stats.totalJourneys++;
+            }
+        }
+    }
+    // Convert to array
+    const result = [];
+    for (const [touchpoint, stats] of statsMap) {
+        const avgLcp = stats.lcpValues.length > 0
+            ? stats.lcpValues.reduce((a, b) => a + b, 0) / stats.lcpValues.length
+            : null;
+        // Performance impact: how much better do converting journeys perform here?
+        const conversionRate = stats.totalJourneys > 0
+            ? stats.convertingJourneys / stats.totalJourneys
+            : 0;
+        result.push({
+            touchpoint,
+            sessions: stats.sessions,
+            firstTouchConversions: stats.firstTouch,
+            lastTouchConversions: stats.lastTouch,
+            linearConversions: stats.linear,
+            positionBasedConversions: stats.positionBased,
+            avgLcp,
+            performanceImpactScore: conversionRate,
+        });
+    }
+    // Sort by first-touch conversions
+    result.sort((a, b) => b.firstTouchConversions - a.firstTouchConversions);
+    return result;
+}
+/**
+ * Analyze performance impact at different journey stages.
+ */
+export function analyzePerformanceInfluence(journeys) {
+    // Get first-touch LCP for converting vs non-converting journeys
+    const convertingFirstLcp = [];
+    const nonConvertingFirstLcp = [];
+    const convertingLastLcp = [];
+    const nonConvertingLastLcp = [];
+    for (const journey of journeys) {
+        if (journey.touchpoints.length === 0)
+            continue;
+        const first = journey.touchpoints[0];
+        const last = journey.touchpoints[journey.touchpoints.length - 1];
+        if (journey.converted) {
+            if (first.lcp !== null)
+                convertingFirstLcp.push(first.lcp);
+            if (last.lcp !== null)
+                convertingLastLcp.push(last.lcp);
+        }
+        else {
+            if (first.lcp !== null)
+                nonConvertingFirstLcp.push(first.lcp);
+            if (last.lcp !== null)
+                nonConvertingLastLcp.push(last.lcp);
+        }
+    }
+    // Simple correlation: difference in means
+    const firstDiff = average(nonConvertingFirstLcp) - average(convertingFirstLcp);
+    const lastDiff = average(nonConvertingLastLcp) - average(convertingLastLcp);
+    // Normalize to 0-1 scale (higher = more impact)
+    const maxDiff = Math.max(Math.abs(firstDiff), Math.abs(lastDiff), 1);
+    const firstTouchCorrelation = Math.min(1, Math.abs(firstDiff) / maxDiff);
+    const lastTouchCorrelation = Math.min(1, Math.abs(lastDiff) / maxDiff);
+    const criticalTouchpoint = firstTouchCorrelation > lastTouchCorrelation
+        ? 'first_touch'
+        : 'last_touch';
+    return {
+        firstTouchCorrelation,
+        lastTouchCorrelation,
+        criticalTouchpoint,
+    };
+}
+/**
+ * Generate full attribution report.
+ */
+export function generateAttributionReport(sessions, model = 'first_touch', groupBy = 'pageType') {
+    const journeys = buildUserJourneys(sessions);
+    const touchpointStats = calculateAttribution(journeys, groupBy);
+    const performanceInfluence = analyzePerformanceInfluence(journeys);
+    const insights = [];
+    const recommendations = [];
+    // Top performers by different models
+    const byFirstTouch = [...touchpointStats].sort((a, b) => b.firstTouchConversions - a.firstTouchConversions);
+    const byLastTouch = [...touchpointStats].sort((a, b) => b.lastTouchConversions - a.lastTouchConversions);
+    if (byFirstTouch.length > 0 && byLastTouch.length > 0) {
+        if (byFirstTouch[0].touchpoint !== byLastTouch[0].touchpoint) {
+            insights.push(`Attribution varies: ${byFirstTouch[0].touchpoint} leads first-touch, ${byLastTouch[0].touchpoint} leads last-touch`);
+        }
+    }
+    // Performance insight
+    if (performanceInfluence.firstTouchCorrelation > performanceInfluence.lastTouchCorrelation) {
+        insights.push('First impression performance has higher conversion impact');
+        recommendations.push('Prioritize landing page performance optimization');
+    }
+    else {
+        insights.push('Final touchpoint performance has higher conversion impact');
+        recommendations.push('Focus on checkout/conversion page performance');
+    }
+    // High-value touchpoints with poor performance
+    const highValuePoorPerf = touchpointStats.filter(tp => tp.firstTouchConversions > 0 && tp.avgLcp !== null && tp.avgLcp > 3000);
+    if (highValuePoorPerf.length > 0) {
+        recommendations.push(`Performance opportunity: ${highValuePoorPerf[0].touchpoint} has high conversions but ${highValuePoorPerf[0].avgLcp.toFixed(0)}ms LCP`);
+    }
+    return {
+        model,
+        touchpointStats,
+        insights,
+        recommendations,
+        performanceInfluence,
+    };
+}
+// =============================================================================
+// REPORT GENERATION
+// =============================================================================
+/**
+ * Generate markdown report for attribution analysis.
+ */
+export function generateAttributionMarkdown(report) {
+    const lines = [];
+    lines.push('## Attribution Analysis');
+    lines.push('');
+    lines.push(`**Model**: ${report.model.replace('_', ' ')}`);
+    lines.push('');
+    // Insights
+    if (report.insights.length > 0) {
+        lines.push('### Insights');
+        lines.push('');
+        for (const insight of report.insights) {
+            lines.push(`- ${insight}`);
+        }
+        lines.push('');
+    }
+    // Recommendations
+    if (report.recommendations.length > 0) {
+        lines.push('### Recommendations');
+        lines.push('');
+        for (const rec of report.recommendations) {
+            lines.push(`- ${rec}`);
+        }
+        lines.push('');
+    }
+    // Performance influence
+    lines.push('### Performance Influence');
+    lines.push('');
+    lines.push(`| Touchpoint | Correlation |`);
+    lines.push(`|------------|-------------|`);
+    lines.push(`| First Touch | ${(report.performanceInfluence.firstTouchCorrelation * 100).toFixed(1)}% |`);
+    lines.push(`| Last Touch | ${(report.performanceInfluence.lastTouchCorrelation * 100).toFixed(1)}% |`);
+    lines.push('');
+    lines.push(`**Critical touchpoint**: ${report.performanceInfluence.criticalTouchpoint.replace('_', ' ')}`);
+    lines.push('');
+    // Attribution table
+    lines.push('### Touchpoint Attribution');
+    lines.push('');
+    lines.push('| Touchpoint | Sessions | First | Last | Linear | Position | LCP |');
+    lines.push('|------------|----------|-------|------|--------|----------|-----|');
+    for (const tp of report.touchpointStats.slice(0, 10)) {
+        const lcp = tp.avgLcp ? `${tp.avgLcp.toFixed(0)}ms` : 'N/A';
+        lines.push(`| ${tp.touchpoint} | ${tp.sessions.toLocaleString()} | ${tp.firstTouchConversions} | ${tp.lastTouchConversions} | ${tp.linearConversions.toFixed(1)} | ${tp.positionBasedConversions.toFixed(1)} | ${lcp} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+function average(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+//# sourceMappingURL=attribution.js.map

package/dist/empirical/attribution.js.map

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

package/dist/empirical/cohort.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Cohort Analysis
+ *
+ * Track same users over time to understand:
+ * - How does performance affect repeat purchases?
+ * - Do users with good first-experience return more?
+ * - Lifetime value by performance cohort
+ *
+ * @author Kanmi Obasa <i@kanmiobasa.com>
+ */
+import type { SessionData } from './datadog-session-query.js';
+export type CohortType = 'performance' | 'time' | 'acquisition';
+export interface PerformanceCohort {
+    /** Cohort identifier */
+    cohortId: string;
+    /** Cohort description */
+    description: string;
+    /** Performance range (e.g., 0-2500ms LCP) */
+    range: {
+        min: number;
+        max: number;
+    };
+    /** Unique users in cohort */
+    uniqueUsers: number;
+    /** Total sessions */
+    totalSessions: number;
+    /** Sessions per user */
+    avgSessionsPerUser: number;
+    /** First-session conversion rate */
+    firstSessionCvr: number;
+    /** Repeat purchase rate */
+    repeatPurchaseRate: number;
+    /** Average order value */
+    aov: number;
+    /** Lifetime value (estimated) */
+    ltv: number;
+}
+export interface TimeCohort {
+    /** Week identifier (e.g., "2025-W01") */
+    weekId: string;
+    /** Users acquired this week */
+    newUsers: number;
+    /** Week 0 conversions (same week) */
+    week0Conversions: number;
+    /** Week 1 conversions */
+    week1Conversions: number;
+    /** Week 2 conversions */
+    week2Conversions: number;
+    /** Week 3+ conversions */
+    week3PlusConversions: number;
+    /** Total conversions */
+    totalConversions: number;
+    /** Retention rate */
+    retentionRate: number;
+}
+export interface CohortAnalysis {
+    type: CohortType;
+    performanceCohorts?: PerformanceCohort[];
+    timeCohorts?: TimeCohort[];
+    insights: string[];
+    recommendations: string[];
+}
+/**
+ * Analyze users by performance cohort.
+ */
+export declare function analyzePerformanceCohorts(sessions: SessionData[], metric?: 'lcp' | 'inp' | 'cls'): CohortAnalysis;
+/**
+ * Analyze users by acquisition time cohort.
+ */
+export declare function analyzeTimeCohorts(sessions: SessionData[]): CohortAnalysis;
+/**
+ * Generate markdown report for cohort analysis.
+ */
+export declare function generateCohortMarkdown(analysis: CohortAnalysis): string;
+//# sourceMappingURL=cohort.d.ts.map

package/dist/empirical/cohort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohort.d.ts","sourceRoot":"","sources":["../../src/empirical/cohort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAM9D,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,MAAM,GAAG,aAAa,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,0BAA0B;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACzC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,EAAE,EACvB,MAAM,GAAE,KAAK,GAAG,KAAK,GAAG,KAAa,GACpC,cAAc,CAuHhB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,cAAc,CA4G1E;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAyDvE"}