@contractspec/lib.analytics 1.56.1 → 1.58.0

package/dist/node/funnel/index.js

@@ -0,0 +1,68 @@
+// src/funnel/analyzer.ts
+class FunnelAnalyzer {
+  analyze(events, definition) {
+    const windowMs = (definition.windowHours ?? 72) * 60 * 60 * 1000;
+    const eventsByUser = groupByUser(events);
+    const stepCounts = definition.steps.map(() => 0);
+    for (const userEvents of eventsByUser.values()) {
+      const completionIndex = this.evaluateUser(userEvents, definition.steps, windowMs);
+      completionIndex.forEach((hit, stepIdx) => {
+        if (hit) {
+          stepCounts[stepIdx] = (stepCounts[stepIdx] ?? 0) + 1;
+        }
+      });
+    }
+    const totalUsers = eventsByUser.size;
+    const steps = definition.steps.map((step, index) => {
+      const prevCount = index === 0 ? totalUsers : stepCounts[index - 1] || 1;
+      const count = stepCounts[index] ?? 0;
+      const conversionRate = prevCount === 0 ? 0 : Number((count / prevCount).toFixed(3));
+      const dropOffRate = Number((1 - conversionRate).toFixed(3));
+      return { step, count, conversionRate, dropOffRate };
+    });
+    return {
+      definition,
+      totalUsers,
+      steps
+    };
+  }
+  evaluateUser(events, steps, windowMs) {
+    const sorted = [...events].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const completion = Array(steps.length).fill(false);
+    let cursor = 0;
+    let anchorTime;
+    for (const event of sorted) {
+      const step = steps[cursor];
+      if (!step)
+        break;
+      if (event.name !== step.eventName)
+        continue;
+      if (step.match && !step.match(event))
+        continue;
+      const eventTime = new Date(event.timestamp).getTime();
+      if (cursor === 0) {
+        anchorTime = eventTime;
+        completion[cursor] = true;
+        cursor += 1;
+        continue;
+      }
+      if (anchorTime && eventTime - anchorTime <= windowMs) {
+        completion[cursor] = true;
+        cursor += 1;
+      }
+    }
+    return completion;
+  }
+}
+function groupByUser(events) {
+  const map = new Map;
+  for (const event of events) {
+    const list = map.get(event.userId) ?? [];
+    list.push(event);
+    map.set(event.userId, list);
+  }
+  return map;
+}
+export {
+  FunnelAnalyzer
+};

package/dist/node/growth/hypothesis-generator.js

@@ -0,0 +1,46 @@
+// src/growth/hypothesis-generator.ts
+class GrowthHypothesisGenerator {
+  minDelta;
+  constructor(options) {
+    this.minDelta = options?.minDelta ?? 0.05;
+  }
+  generate(metrics) {
+    return metrics.map((metric) => this.fromMetric(metric)).filter((hypothesis) => Boolean(hypothesis));
+  }
+  fromMetric(metric) {
+    const change = this.delta(metric);
+    if (Math.abs(change) < this.minDelta)
+      return null;
+    const direction = change > 0 ? "rising" : "declining";
+    const statement = this.statement(metric, change, direction);
+    return {
+      statement,
+      metric: metric.name,
+      confidence: Math.abs(change) > 0.2 ? "high" : "medium",
+      impact: this.impact(metric)
+    };
+  }
+  delta(metric) {
+    if (metric.previous == null)
+      return 0;
+    const prev = metric.previous || 1;
+    return (metric.current - prev) / Math.abs(prev);
+  }
+  impact(metric) {
+    if (metric.target && metric.current < metric.target * 0.8)
+      return "high";
+    if (metric.target && metric.current < metric.target)
+      return "medium";
+    return "low";
+  }
+  statement(metric, change, direction) {
+    const percent = Math.abs(parseFloat((change * 100).toFixed(1)));
+    if (direction === "declining") {
+      return `${metric.name} is down ${percent}% vs last period; test new onboarding prompts to recover activation.`;
+    }
+    return `${metric.name} grew ${percent}% period-over-period; double down with expanded experiment or pricing test.`;
+  }
+}
+export {
+  GrowthHypothesisGenerator
+};

package/dist/node/growth/index.js

@@ -0,0 +1,46 @@
+// src/growth/hypothesis-generator.ts
+class GrowthHypothesisGenerator {
+  minDelta;
+  constructor(options) {
+    this.minDelta = options?.minDelta ?? 0.05;
+  }
+  generate(metrics) {
+    return metrics.map((metric) => this.fromMetric(metric)).filter((hypothesis) => Boolean(hypothesis));
+  }
+  fromMetric(metric) {
+    const change = this.delta(metric);
+    if (Math.abs(change) < this.minDelta)
+      return null;
+    const direction = change > 0 ? "rising" : "declining";
+    const statement = this.statement(metric, change, direction);
+    return {
+      statement,
+      metric: metric.name,
+      confidence: Math.abs(change) > 0.2 ? "high" : "medium",
+      impact: this.impact(metric)
+    };
+  }
+  delta(metric) {
+    if (metric.previous == null)
+      return 0;
+    const prev = metric.previous || 1;
+    return (metric.current - prev) / Math.abs(prev);
+  }
+  impact(metric) {
+    if (metric.target && metric.current < metric.target * 0.8)
+      return "high";
+    if (metric.target && metric.current < metric.target)
+      return "medium";
+    return "low";
+  }
+  statement(metric, change, direction) {
+    const percent = Math.abs(parseFloat((change * 100).toFixed(1)));
+    if (direction === "declining") {
+      return `${metric.name} is down ${percent}% vs last period; test new onboarding prompts to recover activation.`;
+    }
+    return `${metric.name} grew ${percent}% period-over-period; double down with expanded experiment or pricing test.`;
+  }
+}
+export {
+  GrowthHypothesisGenerator
+};